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

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