docs/developer-guide/ocp-plugin-developer-guide.rst

   1 OCP Plugin Developer Guide
   2 ==========================
   3
   4 This document is intended for both OCP (ORI [Open Radio Interface] C&M
   5 [Control and Management] Protocol) agent developers and OpenDaylight
   6 service/application developers. It describes essential information
   7 needed to implement an OCP agent that is capable of interoperating with
   8 the OCP plugin running in OpenDaylight, including the OCP connection
   9 establishment and state machines used on both ends of the connection. It
  10 also provides a detailed description of the northbound/southbound APIs
  11 that the OCP plugin exposes to allow automation and programmability.
  12
  13 Overview
  14 --------
  15
  16 OCP is an ETSI standard protocol for control and management of Remote
  17 Radio Head (RRH) equipment. The OCP Project addresses the need for a
  18 southbound plugin that allows applications and controller services to
  19 interact with RRHs using OCP. The OCP southbound plugin will allow
  20 applications acting as a Radio Equipment Control (REC) to interact with
  21 RRHs that support an OCP agent.
  22
  23 .. figure:: ./images/ocpplugin/ocp-sb-plugin.jpg
  24    :alt: OCP southbound plugin
  25
  26    OCP southbound plugin
  27
  28 Architecture
  29 ------------
  30
  31 OCP is a vendor-neutral standard communications interface defined to
  32 enable control and management between RE and REC of an ORI architecture.
  33 The OCP Plugin supports the implementation of the OCP specification; it
  34 is based on the Model Driven Service Abstraction Layer (MD-SAL)
  35 architecture.
  36
  37 The OCP Plugin project consists of three main components: OCP southbound
  38 plugin, OCP protocol library and OCP service. For details on each of
  39 them, refer to the OCP Plugin User Guide.
  40
  41 .. figure:: ./images/ocpplugin/plugin-design.jpg
  42    :alt: Overall architecture
  43
  44    Overall architecture
  45
  46 Connection Establishment
  47 ------------------------
  48
  49 The OCP layer is transported over a TCP/IP connection established
  50 between the RE and the REC. OCP provides the following functions:
  51
  52 -  Control & Management of the RE by the REC
  53
  54 -  Transport of AISG/3GPP Iuant Layer 7 messages and alarms between REC
  55    and RE
  56
  57 Hello Message
  58 ~~~~~~~~~~~~~
  59
  60 Hello message is used by the OCP agent during connection setup. It is
  61 used for version negotiation. When the connection is established, the
  62 OCP agent immediately sends a Hello message with the version field set
  63 to highest OCP version supported by itself, along with the verdor ID and
  64 serial number of the radio head it is running on.
  65
  66 The combinaiton of the verdor ID and serial number will be used by the
  67 OCP plugin to uniquely identify a managed radio head. When not receiving
  68 reply from the OCP plugin, the OCP agent can resend Hello message with
  69 pre-defined Hello timeout (THLO) and Hello resend times (NHLO).
  70
  71 According to ORI spec, the default value of TCP Link Monitoring Timer
  72 (TTLM) is 50 seconds. The RE shall trigger an OCP layer restart while
  73 TTLM expires in RE or the RE detects a TCP link failure. So we may
  74 define NHLO \* THLO = 50 seconds (e.g. NHLO = 10, THLO = 5 seconds).
  75
  76 By nature the Hello message is a new type of indication, and it contains
  77 supported OCP version, vendor ID and serial number as shown below.
  78
  79 **Hello message.**
  80
  81 ::
  82
  83     <?xml version="1.0" encoding="UTF-8"?>
  84     <msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
  85       <header>
  86         <msgType>IND</msgType>
  87         <msgUID>0</msgUID>
  88       </header>
  89       <body>
  90         <helloInd>
  91           <version>4.1.1</version>
  92           <vendorId>XYZ</vendorId>
  93           <serialNumber>ABC123</serialNumber>
  94         </helloInd>
  95       </body>
  96     </msg>
  97
  98 Ack Message
  99 ~~~~~~~~~~~
 100
 101 Hello from the OCP agent will always make the OCP plugin respond with
 102 ACK. In case everything is OK, it will be ACK(OK). In case something is
 103 wrong, it will be ACK(FAIL).
 104
 105 If the OCP agent receives ACK(OK), it goes to Established state. If the
 106 OCP agent receives ACK(FAIL), it goes to Maintenance state. The failure
 107 code and reason of ACK(FAIL) are defined as below:
 108
 109 -  FAIL\_OCP\_VERSION (OCP version not supported)
 110
 111 -  FAIL\_NO\_MORE\_CAPACITY (OCP plugin cannot control any more radio
 112    heads)
 113
 114 The result inside Ack message indicates OK or FAIL with different
 115 reasons.
 116
 117 **Ack message.**
 118
 119 ::
 120
 121     <?xml version="1.0" encoding="UTF-8"?>
 122     <msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
 123       <header>
 124         <msgType>ACK</msgType>
 125         <msgUID>0</msgUID>
 126       </header>
 127       <body>
 128         <helloAck>
 129           <result>FAIL_OCP_VERSION</result>
 130         </helloAck>
 131       </body>
 132     </msg>
 133
 134 State Machines
 135 ~~~~~~~~~~~~~~
 136
 137 The following figures illustrate the Finite State Machine (FSM) of the
 138 OCP agent and OCP plugin for new connection procedure.
 139
 140 .. figure:: ./images/ocpplugin/ocpagent-state-machine.jpg
 141    :alt: OCP agent state machine
 142
 143    OCP agent state machine
 144
 145 .. figure:: ./images/ocpplugin/ocpplugin-state-machine.jpg
 146    :alt: OCP plugin state machine
 147
 148    OCP plugin state machine
 149
 150 Northbound APIs
 151 ---------------
 152
 153 There are ten exposed northbound APIs: health-check, set-time, re-reset,
 154 get-param, modify-param, create-obj, delete-obj, get-state, modify-state
 155 and get-fault
 156
 157 health-check
 158 ~~~~~~~~~~~~
 159
 160 The Health Check procedure allows the application to verify that the OCP
 161 layer is functioning correctly at the RE.
 162
 163 Default URL:
 164 http://localhost:8181/restconf/operations/ocp-service:health-check-nb
 165
 166 POST Input
 167 ^^^^^^^^^^
 168
 169 +--------------------+----------+--------------------+--------------------+----------+
 170 | Field Name         | Type     | Description        | Example            | Required |
 171 |                    |          |                    |                    | ?        |
 172 +====================+==========+====================+====================+==========+
 173 | nodeId             | String   | Inventory node     | ocp:MTI-101-200    | Yes      |
 174 |                    |          | reference for OCP  |                    |          |
 175 |                    |          | radio head         |                    |          |
 176 +--------------------+----------+--------------------+--------------------+----------+
 177 | tcpLinkMonTimeout  | unsigned | TCP Link           | 50                 | Yes      |
 178 |                    | Short    | Monitoring Timeout |                    |          |
 179 |                    |          | (unit: seconds)    |                    |          |
 180 +--------------------+----------+--------------------+--------------------+----------+
 181
 182 **Example.**
 183
 184 ::
 185
 186     {
 187         "health-check-nb": {
 188             "input": {
 189                 "nodeId": "ocp:MTI-101-200",
 190                 "tcpLinkMonTimeout": "50"
 191             }
 192         }
 193     }
 194
 195 POST Output
 196 ^^^^^^^^^^^
 197
 198 +--------------------+--------------------+--------------------------------------+
 199 | Field Name         | Type               | Description                          |
 200 +====================+====================+======================================+
 201 | result             | String, enumerated | Common default result codes          |
 202 +--------------------+--------------------+--------------------------------------+
 203
 204 **Example.**
 205
 206 ::
 207
 208     {
 209         "output": {
 210             "result": "SUCCESS"
 211         }
 212     }
 213
 214 set-time
 215 ~~~~~~~~
 216
 217 The Set Time procedure allows the application to set/update the absolute
 218 time reference that shall be used by the RE.
 219
 220 Default URL:
 221 http://localhost:8181/restconf/operations/ocp-service:set-time-nb
 222
 223 POST Input
 224 ^^^^^^^^^^
 225
 226 +------------+------------+----------------------+----------------------+------------+
 227 | Field Name | Type       | Description          | Example              | Required?  |
 228 +============+============+======================+======================+============+
 229 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 230 |            |            | reference for OCP    |                      |            |
 231 |            |            | radio head           |                      |            |
 232 +------------+------------+----------------------+----------------------+------------+
 233 | newTime    | dateTime   | New datetime setting | 2016-04-26T10:23:00- | Yes        |
 234 |            |            | for radio head       | 05:00                |            |
 235 +------------+------------+----------------------+----------------------+------------+
 236
 237 **Example.**
 238
 239 ::
 240
 241     {
 242         "set-time-nb": {
 243             "input": {
 244                 "nodeId": "ocp:MTI-101-200",
 245                 "newTime": "2016-04-26T10:23:00-05:00"
 246             }
 247         }
 248     }
 249
 250 POST Output
 251 ^^^^^^^^^^^
 252
 253 +--------------------+--------------------+--------------------------------------+
 254 | Field Name         | Type               | Description                          |
 255 +====================+====================+======================================+
 256 | result             | String, enumerated | Common default result codes +        |
 257 |                    |                    | FAIL\_INVALID\_TIMEDATA              |
 258 +--------------------+--------------------+--------------------------------------+
 259
 260 **Example.**
 261
 262 ::
 263
 264     {
 265         "output": {
 266             "result": "SUCCESS"
 267         }
 268     }
 269
 270 re-reset
 271 ~~~~~~~~
 272
 273 The RE Reset procedure allows the application to reset a specific RE.
 274
 275 Default URL:
 276 http://localhost:8181/restconf/operations/ocp-service:re-reset-nb
 277
 278 POST Input
 279 ^^^^^^^^^^
 280
 281 +------------+------------+----------------------+----------------------+------------+
 282 | Field Name | Type       | Description          | Example              | Required?  |
 283 +============+============+======================+======================+============+
 284 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 285 |            |            | reference for OCP    |                      |            |
 286 |            |            | radio head           |                      |            |
 287 +------------+------------+----------------------+----------------------+------------+
 288
 289 **Example.**
 290
 291 ::
 292
 293     {
 294         "re-reset-nb": {
 295             "input": {
 296                 "nodeId": "ocp:MTI-101-200"
 297             }
 298         }
 299     }
 300
 301 POST Output
 302 ^^^^^^^^^^^
 303
 304 +--------------------+--------------------+--------------------------------------+
 305 | Field Name         | Type               | Description                          |
 306 +====================+====================+======================================+
 307 | result             | String, enumerated | Common default result codes          |
 308 +--------------------+--------------------+--------------------------------------+
 309
 310 **Example.**
 311
 312 ::
 313
 314     {
 315         "output": {
 316             "result": "SUCCESS"
 317         }
 318     }
 319
 320 get-param
 321 ~~~~~~~~~
 322
 323 The Object Parameter Reporting procedure allows the application to
 324 retrieve the following information:
 325
 326 1. the defined object types and instances within the Resource Model of
 327    the RE
 328
 329 2. the values of the parameters of the objects
 330
 331 Default URL:
 332 http://localhost:8181/restconf/operations/ocp-service:get-param-nb
 333
 334 POST Input
 335 ^^^^^^^^^^
 336
 337 +------------+------------+----------------------+----------------------+------------+
 338 | Field Name | Type       | Description          | Example              | Required?  |
 339 +============+============+======================+======================+============+
 340 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 341 |            |            | reference for OCP    |                      |            |
 342 |            |            | radio head           |                      |            |
 343 +------------+------------+----------------------+----------------------+------------+
 344 | objId      | String     | Object ID            | RxSigPath\_5G:1      | Yes        |
 345 +------------+------------+----------------------+----------------------+------------+
 346 | paramName  | String     | Parameter name       | dataLink             | Yes        |
 347 +------------+------------+----------------------+----------------------+------------+
 348
 349 **Example.**
 350
 351 ::
 352
 353     {
 354         "get-param-nb": {
 355             "input": {
 356                 "nodeId": "ocp:MTI-101-200",
 357                 "objId": "RxSigPath_5G:1",
 358                 "paramName": "dataLink"
 359             }
 360         }
 361     }
 362
 363 POST Output
 364 ^^^^^^^^^^^
 365
 366 +--------------------+--------------------+--------------------------------------+
 367 | Field Name         | Type               | Description                          |
 368 +====================+====================+======================================+
 369 | id                 | String             | Object ID                            |
 370 +--------------------+--------------------+--------------------------------------+
 371 | name               | String             | Object parameter name                |
 372 +--------------------+--------------------+--------------------------------------+
 373 | value              | String             | Object parameter value               |
 374 +--------------------+--------------------+--------------------------------------+
 375 | result             | String, enumerated | Common default result codes +        |
 376 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 377 |                    |                    | "FAIL\_UNKNOWN\_PARAM"               |
 378 +--------------------+--------------------+--------------------------------------+
 379
 380 **Example.**
 381
 382 ::
 383
 384     {
 385         "output": {
 386             "obj": [
 387                 {
 388                     "id": "RxSigPath_5G:1",
 389                     "param": [
 390                         {
 391                             "name": "dataLink",
 392                             "value": "dataLink:1"
 393                         }
 394                     ]
 395                 }
 396             ],
 397             "result": "SUCCESS"
 398         }
 399     }
 400
 401 modify-param
 402 ~~~~~~~~~~~~
 403
 404 The Object Parameter Modification procedure allows the application to
 405 configure the values of the parameters of the objects identified by the
 406 Resource Model.
 407
 408 Default URL:
 409 http://localhost:8181/restconf/operations/ocp-service:modify-param-nb
 410
 411 POST Input
 412 ^^^^^^^^^^
 413
 414 +------------+------------+----------------------+----------------------+------------+
 415 | Field Name | Type       | Description          | Example              | Required?  |
 416 +============+============+======================+======================+============+
 417 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 418 |            |            | reference for OCP    |                      |            |
 419 |            |            | radio head           |                      |            |
 420 +------------+------------+----------------------+----------------------+------------+
 421 | objId      | String     | Object ID            | RxSigPath\_5G:1      | Yes        |
 422 +------------+------------+----------------------+----------------------+------------+
 423 | name       | String     | Object parameter     | dataLink             | Yes        |
 424 |            |            | name                 |                      |            |
 425 +------------+------------+----------------------+----------------------+------------+
 426 | value      | String     | Object parameter     | dataLink:1           | Yes        |
 427 |            |            | value                |                      |            |
 428 +------------+------------+----------------------+----------------------+------------+
 429
 430 **Example.**
 431
 432 ::
 433
 434     {
 435         "modify-param-nb": {
 436             "input": {
 437                 "nodeId": "ocp:MTI-101-200",
 438                 "objId": "RxSigPath_5G:1",
 439                 "param": [
 440                     {
 441                         "name": "dataLink",
 442                         "value": "dataLink:1"
 443                     }
 444                 ]
 445             }
 446         }
 447     }
 448
 449 POST Output
 450 ^^^^^^^^^^^
 451
 452 +--------------------+--------------------+--------------------------------------+
 453 | Field Name         | Type               | Description                          |
 454 +====================+====================+======================================+
 455 | objId              | String             | Object ID                            |
 456 +--------------------+--------------------+--------------------------------------+
 457 | globResult         | String, enumerated | Common default result codes +        |
 458 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 459 |                    |                    | "FAIL\_PARAMETER\_FAIL",             |
 460 |                    |                    | "FAIL\_NOSUCH\_RESOURCE"             |
 461 +--------------------+--------------------+--------------------------------------+
 462 | name               | String             | Object parameter name                |
 463 +--------------------+--------------------+--------------------------------------+
 464 | result             | String, enumerated | "SUCCESS", "FAIL\_UNKNOWN\_PARAM",   |
 465 |                    |                    | "FAIL\_PARAM\_READONLY",             |
 466 |                    |                    | "FAIL\_PARAM\_LOCKREQUIRED",         |
 467 |                    |                    | "FAIL\_VALUE\_OUTOF\_RANGE",         |
 468 |                    |                    | "FAIL\_VALUE\_TYPE\_ERROR"           |
 469 +--------------------+--------------------+--------------------------------------+
 470
 471 **Example.**
 472
 473 ::
 474
 475     {
 476         "output": {
 477             "objId": "RxSigPath_5G:1",
 478             "globResult": "SUCCESS",
 479             "param": [
 480                 {
 481                     "name": "dataLink",
 482                     "result": "SUCCESS"
 483                 }
 484             ]
 485         }
 486     }
 487
 488 create-obj
 489 ~~~~~~~~~~
 490
 491 The Object Creation procedure allows the application to create and
 492 initialize a new instance of the given object type on the RE.
 493
 494 Default URL:
 495 http://localhost:8181/restconf/operations/ocp-service:create-obj-nb
 496
 497 POST Input
 498 ^^^^^^^^^^
 499
 500 +------------+------------+----------------------+----------------------+------------+
 501 | Field Name | Type       | Description          | Example              | Required?  |
 502 +============+============+======================+======================+============+
 503 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 504 |            |            | reference for OCP    |                      |            |
 505 |            |            | radio head           |                      |            |
 506 +------------+------------+----------------------+----------------------+------------+
 507 | objType    | String     | Object type          | RxSigPath\_5G        | Yes        |
 508 +------------+------------+----------------------+----------------------+------------+
 509 | name       | String     | Object parameter     | dataLink             | No         |
 510 |            |            | name                 |                      |            |
 511 +------------+------------+----------------------+----------------------+------------+
 512 | value      | String     | Object parameter     | dataLink:1           | No         |
 513 |            |            | value                |                      |            |
 514 +------------+------------+----------------------+----------------------+------------+
 515
 516 **Example.**
 517
 518 ::
 519
 520     {
 521         "create-obj-nb": {
 522             "input": {
 523                 "nodeId": "ocp:MTI-101-200",
 524                 "objType": "RxSigPath_5G",
 525                 "param": [
 526                     {
 527                         "name": "dataLink",
 528                         "value": "dataLink:1"
 529                     }
 530                 ]
 531             }
 532         }
 533     }
 534
 535 POST Output
 536 ^^^^^^^^^^^
 537
 538 +--------------------+--------------------+--------------------------------------+
 539 | Field Name         | Type               | Description                          |
 540 +====================+====================+======================================+
 541 | objId              | String             | Object ID                            |
 542 +--------------------+--------------------+--------------------------------------+
 543 | globResult         | String, enumerated | Common default result codes +        |
 544 |                    |                    | "FAIL\_UNKNOWN\_OBJTYPE",            |
 545 |                    |                    | "FAIL\_STATIC\_OBJTYPE",             |
 546 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 547 |                    |                    | "FAIL\_CHILD\_NOTALLOWED",           |
 548 |                    |                    | "FAIL\_OUTOF\_RESOURCES"             |
 549 |                    |                    | "FAIL\_PARAMETER\_FAIL",             |
 550 |                    |                    | "FAIL\_NOSUCH\_RESOURCE"             |
 551 +--------------------+--------------------+--------------------------------------+
 552 | name               | String             | Object parameter name                |
 553 +--------------------+--------------------+--------------------------------------+
 554 | result             | String, enumerated | "SUCCESS", "FAIL\_UNKNOWN\_PARAM",   |
 555 |                    |                    | "FAIL\_PARAM\_READONLY",             |
 556 |                    |                    | "FAIL\_PARAM\_LOCKREQUIRED",         |
 557 |                    |                    | "FAIL\_VALUE\_OUTOF\_RANGE",         |
 558 |                    |                    | "FAIL\_VALUE\_TYPE\_ERROR"           |
 559 +--------------------+--------------------+--------------------------------------+
 560
 561 **Example.**
 562
 563 ::
 564
 565     {
 566         "output": {
 567             "objId": "RxSigPath_5G:0",
 568             "globResult": "SUCCESS",
 569             "param": [
 570                 {
 571                     "name": "dataLink",
 572                     "result": "SUCCESS"
 573                 }
 574             ]
 575         }
 576     }
 577
 578 delete-obj
 579 ~~~~~~~~~~
 580
 581 The Object Deletion procedure allows the application to delete a given
 582 object instance and recursively its entire child objects on the RE.
 583
 584 Default URL:
 585 http://localhost:8181/restconf/operations/ocp-service:delete-obj-nb
 586
 587 POST Input
 588 ^^^^^^^^^^
 589
 590 +------------+------------+----------------------+----------------------+------------+
 591 | Field Name | Type       | Description          | Example              | Required?  |
 592 +============+============+======================+======================+============+
 593 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 594 |            |            | reference for OCP    |                      |            |
 595 |            |            | radio head           |                      |            |
 596 +------------+------------+----------------------+----------------------+------------+
 597 | objId      | String     | Object ID            | RxSigPath\_5G:1      | Yes        |
 598 +------------+------------+----------------------+----------------------+------------+
 599
 600 **Example.**
 601
 602 ::
 603
 604     {
 605         "delete-obj-nb": {
 606             "input": {
 607                 "nodeId": "ocp:MTI-101-200",
 608                 "obj-id": "RxSigPath_5G:0"
 609             }
 610         }
 611     }
 612
 613 POST Output
 614 ^^^^^^^^^^^
 615
 616 +--------------------+--------------------+--------------------------------------+
 617 | Field Name         | Type               | Description                          |
 618 +====================+====================+======================================+
 619 | result             | String, enumerated | Common default result codes +        |
 620 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 621 |                    |                    | "FAIL\_STATIC\_OBJTYPE",             |
 622 |                    |                    | "FAIL\_LOCKREQUIRED"                 |
 623 +--------------------+--------------------+--------------------------------------+
 624
 625 **Example.**
 626
 627 ::
 628
 629     {
 630         "output": {
 631             "result": "SUCCESS"
 632         }
 633     }
 634
 635 get-state
 636 ~~~~~~~~~
 637
 638 The Object State Reporting procedure allows the application to acquire
 639 the current state (for the requested state type) of one or more objects
 640 of the RE resource model, and additionally configure event-triggered
 641 reporting of the detected state changes for all state types of the
 642 indicated objects.
 643
 644 Default URL:
 645 http://localhost:8181/restconf/operations/ocp-service:get-state-nb
 646
 647 POST Input
 648 ^^^^^^^^^^
 649
 650 +--------------------+----------+--------------------+--------------------+----------+
 651 | Field Name         | Type     | Description        | Example            | Required |
 652 |                    |          |                    |                    | ?        |
 653 +====================+==========+====================+====================+==========+
 654 | nodeId             | String   | Inventory node     | ocp:MTI-101-200    | Yes      |
 655 |                    |          | reference for OCP  |                    |          |
 656 |                    |          | radio head         |                    |          |
 657 +--------------------+----------+--------------------+--------------------+----------+
 658 | objId              | String   | Object ID          | RxSigPath\_5G:1    | Yes      |
 659 +--------------------+----------+--------------------+--------------------+----------+
 660 | stateType          | String,  | Valid values:      | ALL                | Yes      |
 661 |                    | enumerat | "AST", "FST",      |                    |          |
 662 |                    | ed       | "ALL"              |                    |          |
 663 +--------------------+----------+--------------------+--------------------+----------+
 664 | eventDrivenReporti | Boolean  | Event-triggered    | true               | Yes      |
 665 | ng                 |          | reporting of state |                    |          |
 666 |                    |          | change             |                    |          |
 667 +--------------------+----------+--------------------+--------------------+----------+
 668
 669 **Example.**
 670
 671 ::
 672
 673     {
 674         "get-state-nb": {
 675             "input": {
 676                 "nodeId": "ocp:MTI-101-200",
 677                 "objId": "antPort:0",
 678                 "stateType": "ALL",
 679                 "eventDrivenReporting": "true"
 680             }
 681         }
 682     }
 683
 684 POST Output
 685 ^^^^^^^^^^^
 686
 687 +--------------------+--------------------+--------------------------------------+
 688 | Field Name         | Type               | Description                          |
 689 +====================+====================+======================================+
 690 | id                 | String             | Object ID                            |
 691 +--------------------+--------------------+--------------------------------------+
 692 | type               | String, enumerated | State type. Valid values: "AST",     |
 693 |                    |                    | "FST                                 |
 694 +--------------------+--------------------+--------------------------------------+
 695 | value              | String, enumerated | State value. Valid values: For state |
 696 |                    |                    | type = "AST": "LOCKED", "UNLOCKED".  |
 697 |                    |                    | For state type = "FST":              |
 698 |                    |                    | "PRE\_OPERATIONAL", "OPERATIONAL",   |
 699 |                    |                    | "DEGRADED", "FAILED",                |
 700 |                    |                    | "NOT\_OPERATIONAL", "DISABLED"       |
 701 +--------------------+--------------------+--------------------------------------+
 702 | result             | String, enumerated | Common default result codes +        |
 703 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 704 |                    |                    | "FAIL\_UNKNOWN\_STATETYPE",          |
 705 |                    |                    | "FAIL\_VALUE\_OUTOF\_RANGE"          |
 706 +--------------------+--------------------+--------------------------------------+
 707
 708 **Example.**
 709
 710 ::
 711
 712     {
 713         "output": {
 714             "obj": [
 715                 {
 716                     "id": "antPort:0",
 717                     "state": [
 718                         {
 719                             "type": "FST",
 720                             "value": "DISABLED"
 721                         },
 722                         {
 723                             "type": "AST",
 724                             "value": "LOCKED"
 725                         }
 726                     ]
 727                 }
 728             ],
 729             "result": "SUCCESS"
 730         }
 731     }
 732
 733 modify-state
 734 ~~~~~~~~~~~~
 735
 736 The Object State Modification procedure allows the application to
 737 trigger a change in the state of an object of the RE Resource Model.
 738
 739 Default URL:
 740 http://localhost:8181/restconf/operations/ocp-service:modify-state-nb
 741
 742 POST Input
 743 ^^^^^^^^^^
 744
 745 +------------+------------+----------------------+----------------------+------------+
 746 | Field Name | Type       | Description          | Example              | Required?  |
 747 +============+============+======================+======================+============+
 748 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 749 |            |            | reference for OCP    |                      |            |
 750 |            |            | radio head           |                      |            |
 751 +------------+------------+----------------------+----------------------+------------+
 752 | objId      | String     | Object ID            | RxSigPath\_5G:1      | Yes        |
 753 +------------+------------+----------------------+----------------------+------------+
 754 | stateType  | String,    | Valid values: "AST", | AST                  | Yes        |
 755 |            | enumerated | "FST", "ALL"         |                      |            |
 756 +------------+------------+----------------------+----------------------+------------+
 757 | stateValue | String,    | Valid values: For    | LOCKED               | Yes        |
 758 |            | enumerated | state type = "AST":  |                      |            |
 759 |            |            | "LOCKED",            |                      |            |
 760 |            |            | "UNLOCKED". For      |                      |            |
 761 |            |            | state type = "FST":  |                      |            |
 762 |            |            | "PRE\_OPERATIONAL",  |                      |            |
 763 |            |            | "OPERATIONAL",       |                      |            |
 764 |            |            | "DEGRADED",          |                      |            |
 765 |            |            | "FAILED",            |                      |            |
 766 |            |            | "NOT\_OPERATIONAL",  |                      |            |
 767 |            |            | "DISABLED"           |                      |            |
 768 +------------+------------+----------------------+----------------------+------------+
 769
 770 **Example.**
 771
 772 ::
 773
 774     {
 775         "modify-state-nb": {
 776             "input": {
 777                 "nodeId": "ocp:MTI-101-200",
 778                 "objId": "RxSigPath_5G:1",
 779                 "stateType": "AST",
 780                 "stateValue": "LOCKED"
 781             }
 782         }
 783     }
 784
 785 POST Output
 786 ^^^^^^^^^^^
 787
 788 +--------------------+--------------------+--------------------------------------+
 789 | Field Name         | Type               | Description                          |
 790 +====================+====================+======================================+
 791 | objId              | String             | Object ID                            |
 792 +--------------------+--------------------+--------------------------------------+
 793 | stateType          | String, enumerated | State type. Valid values: "AST",     |
 794 |                    |                    | "FST                                 |
 795 +--------------------+--------------------+--------------------------------------+
 796 | stateValue         | String, enumerated | State value. Valid values: For state |
 797 |                    |                    | type = "AST": "LOCKED", "UNLOCKED".  |
 798 |                    |                    | For state type = "FST":              |
 799 |                    |                    | "PRE\_OPERATIONAL", "OPERATIONAL",   |
 800 |                    |                    | "DEGRADED", "FAILED",                |
 801 |                    |                    | "NOT\_OPERATIONAL", "DISABLED"       |
 802 +--------------------+--------------------+--------------------------------------+
 803 | result             | String, enumerated | Common default result codes +        |
 804 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 805 |                    |                    | "FAIL\_UNKNOWN\_STATETYPE",          |
 806 |                    |                    | "FAIL\_UNKNOWN\_STATEVALUE",         |
 807 |                    |                    | "FAIL\_STATE\_READONLY",             |
 808 |                    |                    | "FAIL\_RESOURCE\_UNAVAILABLE",       |
 809 |                    |                    | "FAIL\_RESOURCE\_INUSE",             |
 810 |                    |                    | "FAIL\_PARENT\_CHILD\_CONFLICT",     |
 811 |                    |                    | "FAIL\_PRECONDITION\_NOTMET          |
 812 +--------------------+--------------------+--------------------------------------+
 813
 814 **Example.**
 815
 816 ::
 817
 818     {
 819         "output": {
 820             "objId": "RxSigPath_5G:1",
 821             "stateType": "AST",
 822             "stateValue": "LOCKED",
 823             "result": "SUCCESS",
 824         }
 825     }
 826
 827 get-fault
 828 ~~~~~~~~~
 829
 830 The Fault Reporting procedure allows the application to acquire
 831 information about all current active faults associated with a primary
 832 object, as well as configure the RE to report when the fault status
 833 changes for any of faults associated with the indicated primary object.
 834
 835 Default URL:
 836 http://localhost:8181/restconf/operations/ocp-service:get-fault-nb
 837
 838 POST Input
 839 ^^^^^^^^^^
 840
 841 +------------+------------+----------------------+----------------------+------------+
 842 | Field Name | Type       | Description          | Example              | Required?  |
 843 +============+============+======================+======================+============+
 844 | nodeId     | String     | Inventory node       | ocp:MTI-101-200      | Yes        |
 845 |            |            | reference for OCP    |                      |            |
 846 |            |            | radio head           |                      |            |
 847 +------------+------------+----------------------+----------------------+------------+
 848 | objId      | String     | Object ID            | RE:0                 | Yes        |
 849 +------------+------------+----------------------+----------------------+------------+
 850 | eventDrive | Boolean    | Event-triggered      | true                 | Yes        |
 851 | nReporting |            | reporting of fault   |                      |            |
 852 +------------+------------+----------------------+----------------------+------------+
 853
 854 **Example.**
 855
 856 ::
 857
 858     {
 859         "get-fault-nb": {
 860             "input": {
 861                 "nodeId": "ocp:MTI-101-200",
 862                 "objId": "RE:0",
 863                 "eventDrivenReporting": "true"
 864             }
 865         }
 866     }
 867
 868 POST Output
 869 ^^^^^^^^^^^
 870
 871 +--------------------+--------------------+--------------------------------------+
 872 | Field Name         | Type               | Description                          |
 873 +====================+====================+======================================+
 874 | result             | String, enumerated | Common default result codes +        |
 875 |                    |                    | "FAIL\_UNKNOWN\_OBJECT",             |
 876 |                    |                    | "FAIL\_VALUE\_OUTOF\_RANGE"          |
 877 +--------------------+--------------------+--------------------------------------+
 878 | id (obj)           | String             | Object ID                            |
 879 +--------------------+--------------------+--------------------------------------+
 880 | id (fault)         | String             | Fault ID                             |
 881 +--------------------+--------------------+--------------------------------------+
 882 | severity           | String             | Fault severity                       |
 883 +--------------------+--------------------+--------------------------------------+
 884 | timestamp          | dateTime           | Time stamp                           |
 885 +--------------------+--------------------+--------------------------------------+
 886 | descr              | String             | Text description                     |
 887 +--------------------+--------------------+--------------------------------------+
 888 | affectedObj        | String             | Affected object                      |
 889 +--------------------+--------------------+--------------------------------------+
 890
 891 **Example.**
 892
 893 ::
 894
 895     {
 896         "output": {
 897             "result": "SUCCESS",
 898             "obj": [
 899                 {
 900                     "id": "RE:0",
 901                     "fault": [
 902                         {
 903                             "id": "FAULT_OVERTEMP",
 904                             "severity": "DEGRADED",
 905                             "timestamp": "2012-02-12T16:35:00",
 906                             "descr": "PA temp too high; Pout reduced",
 907                             "affectedObj": [
 908                                 "TxSigPath_EUTRA:0",
 909                                 "TxSigPath_EUTRA:1"
 910                             ]
 911                         },
 912                         {
 913                             "id": "FAULT_VSWR_OUTOF_RANGE",
 914                             "severity": "WARNING",
 915                             "timestamp": "2012-02-12T16:01:05",
 916                         }
 917                     ]
 918                 }
 919             ],
 920         }
 921     }
 922
 923 .. note::
 924
 925     The northbound APIs described above wrap the southbound APIs to make
 926     them accessible to external applications via RESTCONF, as well as
 927     take care of synchronizing the RE resource model between radio heads
 928     and the controller’s datastore. See
 929     applications/ocp-service/src/main/yang/ocp-resourcemodel.yang for
 930     the yang representation of the RE resource model.
 931
 932 Java Interfaces (Southbound APIs)
 933 ---------------------------------
 934
 935 The southbound APIs provide concrete implementation of the following OCP
 936 elementary functions: health-check, set-time, re-reset, get-param,
 937 modify-param, create-obj, delete-obj, get-state, modify-state and
 938 get-fault. Any OpenDaylight services/applications (of course, including
 939 OCP service) wanting to speak OCP to radio heads will need to use them.
 940
 941 SalDeviceMgmtService
 942 ~~~~~~~~~~~~~~~~~~~~
 943
 944 Interface SalDeviceMgmtService defines three methods corresponding to
 945 health-check, set-time and re-reset.
 946
 947 **SalDeviceMgmtService.java.**
 948
 949 ::
 950
 951     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
 952
 953     public interface SalDeviceMgmtService
 954         extends
 955         RpcService
 956     {
 957
 958         Future<RpcResult<HealthCheckOutput>> healthCheck(HealthCheckInput input);
 959
 960         Future<RpcResult<SetTimeOutput>> setTime(SetTimeInput input);
 961
 962         Future<RpcResult<ReResetOutput>> reReset(ReResetInput input);
 963
 964     }
 965
 966 SalConfigMgmtService
 967 ~~~~~~~~~~~~~~~~~~~~
 968
 969 Interface SalConfigMgmtService defines two methods corresponding to
 970 get-param and modify-param.
 971
 972 **SalConfigMgmtService.java.**
 973
 974 ::
 975
 976     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.config.mgmt.rev150811;
 977
 978     public interface SalConfigMgmtService
 979         extends
 980         RpcService
 981     {
 982
 983         Future<RpcResult<GetParamOutput>> getParam(GetParamInput input);
 984
 985         Future<RpcResult<ModifyParamOutput>> modifyParam(ModifyParamInput input);
 986
 987     }
 988
 989 SalObjectLifecycleService
 990 ~~~~~~~~~~~~~~~~~~~~~~~~~
 991
 992 Interface SalObjectLifecycleService defines two methods corresponding to
 993 create-obj and delete-obj.
 994
 995 **SalObjectLifecycleService.java.**
 996
 997 ::
 998
 999     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.lifecycle.rev150811;
1000
1001     public interface SalObjectLifecycleService
1002         extends
1003         RpcService
1004     {
1005
1006         Future<RpcResult<CreateObjOutput>> createObj(CreateObjInput input);
1007
1008         Future<RpcResult<DeleteObjOutput>> deleteObj(DeleteObjInput input);
1009
1010     }
1011
1012 SalObjectStateMgmtService
1013 ~~~~~~~~~~~~~~~~~~~~~~~~~
1014
1015 Interface SalObjectStateMgmtService defines two methods corresponding to
1016 get-state and modify-state.
1017
1018 **SalObjectStateMgmtService.java.**
1019
1020 ::
1021
1022     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
1023
1024     public interface SalObjectStateMgmtService
1025         extends
1026         RpcService
1027     {
1028
1029         Future<RpcResult<GetStateOutput>> getState(GetStateInput input);
1030
1031         Future<RpcResult<ModifyStateOutput>> modifyState(ModifyStateInput input);
1032
1033     }
1034
1035 SalFaultMgmtService
1036 ~~~~~~~~~~~~~~~~~~~
1037
1038 Interface SalFaultMgmtService defines only one method corresponding to
1039 get-fault.
1040
1041 **SalFaultMgmtService.java.**
1042
1043 ::
1044
1045     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
1046
1047     public interface SalFaultMgmtService
1048         extends
1049         RpcService
1050     {
1051
1052         Future<RpcResult<GetFaultOutput>> getFault(GetFaultInput input);
1053
1054     }
1055
1056 Notifications
1057 -------------
1058
1059 In addition to indication messages, the OCP southbound plugin will
1060 translate specific events (e.g., connect, disconnect) coming up from the
1061 OCP protocol library into MD-SAL Notification objects and then publish
1062 them to the MD-SAL. Also, the OCP service will notify the completion of
1063 certain operation via Notification as well.
1064
1065 SalDeviceMgmtListener
1066 ~~~~~~~~~~~~~~~~~~~~~
1067
1068 An onDeviceConnected Notification will be published to the MD-SAL as
1069 soon as a radio head is connected to the controller, and when that radio
1070 head is disconnected the OCP southbound plugin will publish an
1071 onDeviceDisconnected Notification in response to the disconnect event
1072 propagated from the OCP protocol library.
1073
1074 **SalDeviceMgmtListener.java.**
1075
1076 ::
1077
1078     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
1079
1080     public interface SalDeviceMgmtListener
1081         extends
1082         NotificationListener
1083     {
1084
1085         void onDeviceConnected(DeviceConnected notification);
1086
1087         void onDeviceDisconnected(DeviceDisconnected notification);
1088
1089     }
1090
1091 OcpServiceListener
1092 ~~~~~~~~~~~~~~~~~~
1093
1094 The OCP service will publish an onAlignmentCompleted Notification to the
1095 MD-SAL once it has completed the OCP alignment procedure with the radio
1096 head.
1097
1098 **OcpServiceListener.java.**
1099
1100 ::
1101
1102     package org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.ocp.applications.ocp.service.rev150811;
1103
1104     public interface OcpServiceListener
1105         extends
1106         NotificationListener
1107     {
1108
1109         void onAlignmentCompleted(AlignmentCompleted notification);
1110
1111     }
1112
1113 SalObjectStateMgmtListener
1114 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1115
1116 When receiving a state change indication message, the OCP southbound
1117 plugin will propagate the indication message to upper layer
1118 services/applications by publishing a corresponding onStateChangeInd
1119 Notification to the MD-SAL.
1120
1121 **SalObjectStateMgmtListener.java.**
1122
1123 ::
1124
1125     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
1126
1127     public interface SalObjectStateMgmtListener
1128         extends
1129         NotificationListener
1130     {
1131
1132         void onStateChangeInd(StateChangeInd notification);
1133
1134     }
1135
1136 SalFaultMgmtListener
1137 ~~~~~~~~~~~~~~~~~~~~
1138
1139 When receiving a fault indication message, the OCP southbound plugin
1140 will propagate the indication message to upper layer
1141 services/applications by publishing a corresponding onFaultInd
1142 Notification to the MD-SAL.
1143
1144 **SalFaultMgmtListener.java.**
1145
1146 ::
1147
1148     package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
1149
1150     public interface SalFaultMgmtListener
1151         extends
1152         NotificationListener
1153     {
1154
1155         void onFaultInd(FaultInd notification);
1156
1157     }
1158