This document is intended for both OCP (ORI [Open Radio Interface] C&M [Control and Management] Protocol) agent developers and OpenDaylight service/application developers. It describes essential information needed to implement an OCP agent that is capable of interoperating with the OCP plugin running in OpenDaylight, including the OCP connection establishment and state machines used on both ends of the connection. It also provides a detailed description of the northbound/southbound APIs that the OCP plugin exposes to allow automation and programmability.
OCP is an ETSI standard protocol for control and management of Remote Radio Head (RRH) equipment. The OCP Project addresses the need for a southbound plugin that allows applications and controller services to interact with RRHs using OCP. The OCP southbound plugin will allow applications acting as a Radio Equipment Control (REC) to interact with RRHs that support an OCP agent.
OCP is a vendor-neutral standard communications interface defined to enable control and management between RE and REC of an ORI architecture. The OCP Plugin supports the implementation of the OCP specification; it is based on the Model Driven Service Abstraction Layer (MD-SAL) architecture.
The OCP Plugin project consists of three main components: OCP southbound plugin, OCP protocol library and OCP service. For details on each of them, refer to the OCP Plugin User Guide.
The OCP layer is transported over a TCP/IP connection established between the RE and the REC. OCP provides the following functions:
Hello message is used by the OCP agent during connection setup. It is used for version negotiation. When the connection is established, the OCP agent immediately sends a Hello message with the version field set to highest OCP version supported by itself, along with the verdor ID and serial number of the radio head it is running on.
The combinaiton of the verdor ID and serial number will be used by the OCP plugin to uniquely identify a managed radio head. When not receiving reply from the OCP plugin, the OCP agent can resend Hello message with pre-defined Hello timeout (THLO) and Hello resend times (NHLO).
According to ORI spec, the default value of TCP Link Monitoring Timer (TTLM) is 50 seconds. The RE shall trigger an OCP layer restart while TTLM expires in RE or the RE detects a TCP link failure. So we may define NHLO * THLO = 50 seconds (e.g. NHLO = 10, THLO = 5 seconds).
By nature the Hello message is a new type of indication, and it contains supported OCP version, vendor ID and serial number as shown below.
Hello message.
<?xml version="1.0" encoding="UTF-8"?>
<msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
<header>
<msgType>IND</msgType>
<msgUID>0</msgUID>
</header>
<body>
<helloInd>
<version>4.1.1</version>
<vendorId>XYZ</vendorId>
<serialNumber>ABC123</serialNumber>
</helloInd>
</body>
</msg>
Hello from the OCP agent will always make the OCP plugin respond with ACK. In case everything is OK, it will be ACK(OK). In case something is wrong, it will be ACK(FAIL).
If the OCP agent receives ACK(OK), it goes to Established state. If the OCP agent receives ACK(FAIL), it goes to Maintenance state. The failure code and reason of ACK(FAIL) are defined as below:
The result inside Ack message indicates OK or FAIL with different reasons.
Ack message.
<?xml version="1.0" encoding="UTF-8"?>
<msg xmlns="http://uri.etsi.org/ori/002-2/v4.1.1">
<header>
<msgType>ACK</msgType>
<msgUID>0</msgUID>
</header>
<body>
<helloAck>
<result>FAIL_OCP_VERSION</result>
</helloAck>
</body>
</msg>
The following figures illustrate the Finite State Machine (FSM) of the OCP agent and OCP plugin for new connection procedure.
There are ten exposed northbound APIs: health-check, set-time, re-reset, get-param, modify-param, create-obj, delete-obj, get-state, modify-state and get-fault
The Health Check procedure allows the application to verify that the OCP layer is functioning correctly at the RE.
Default URL: http://localhost:8181/restconf/operations/ocp-service:health-check-nb
Field Name | Type | Description | Example | Required ? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
tcpLinkMonTimeout | unsigned Short | TCP Link Monitoring Timeout (unit: seconds) | 50 | Yes |
Example.
{
"health-check-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"tcpLinkMonTimeout": "50"
}
}
}
Field Name | Type | Description |
---|---|---|
result | String, enumerated | Common default result codes |
Example.
{
"output": {
"result": "SUCCESS"
}
}
The Set Time procedure allows the application to set/update the absolute time reference that shall be used by the RE.
Default URL: http://localhost:8181/restconf/operations/ocp-service:set-time-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
newTime | dateTime | New datetime setting for radio head | 2016-04-26T10:23:00- 05:00 | Yes |
Example.
{
"set-time-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"newTime": "2016-04-26T10:23:00-05:00"
}
}
}
Field Name | Type | Description |
---|---|---|
result | String, enumerated | Common default result codes + FAIL_INVALID_TIMEDATA |
Example.
{
"output": {
"result": "SUCCESS"
}
}
The RE Reset procedure allows the application to reset a specific RE.
Default URL: http://localhost:8181/restconf/operations/ocp-service:re-reset-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
Example.
{
"re-reset-nb": {
"input": {
"nodeId": "ocp:MTI-101-200"
}
}
}
Field Name | Type | Description |
---|---|---|
result | String, enumerated | Common default result codes |
Example.
{
"output": {
"result": "SUCCESS"
}
}
The Object Parameter Reporting procedure allows the application to retrieve the following information:
Default URL: http://localhost:8181/restconf/operations/ocp-service:get-param-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RxSigPath_5G:1 | Yes |
paramName | String | Parameter name | dataLink | Yes |
Example.
{
"get-param-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objId": "RxSigPath_5G:1",
"paramName": "dataLink"
}
}
}
Field Name | Type | Description |
---|---|---|
id | String | Object ID |
name | String | Object parameter name |
value | String | Object parameter value |
result | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_UNKNOWN_PARAM” |
Example.
{
"output": {
"obj": [
{
"id": "RxSigPath_5G:1",
"param": [
{
"name": "dataLink",
"value": "dataLink:1"
}
]
}
],
"result": "SUCCESS"
}
}
The Object Parameter Modification procedure allows the application to configure the values of the parameters of the objects identified by the Resource Model.
Default URL: http://localhost:8181/restconf/operations/ocp-service:modify-param-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RxSigPath_5G:1 | Yes |
name | String | Object parameter name | dataLink | Yes |
value | String | Object parameter value | dataLink:1 | Yes |
Example.
{
"modify-param-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objId": "RxSigPath_5G:1",
"param": [
{
"name": "dataLink",
"value": "dataLink:1"
}
]
}
}
}
Field Name | Type | Description |
---|---|---|
objId | String | Object ID |
globResult | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_PARAMETER_FAIL”, “FAIL_NOSUCH_RESOURCE” |
name | String | Object parameter name |
result | String, enumerated | “SUCCESS”, “FAIL_UNKNOWN_PARAM”, “FAIL_PARAM_READONLY”, “FAIL_PARAM_LOCKREQUIRED”, “FAIL_VALUE_OUTOF_RANGE”, “FAIL_VALUE_TYPE_ERROR” |
Example.
{
"output": {
"objId": "RxSigPath_5G:1",
"globResult": "SUCCESS",
"param": [
{
"name": "dataLink",
"result": "SUCCESS"
}
]
}
}
The Object Creation procedure allows the application to create and initialize a new instance of the given object type on the RE.
Default URL: http://localhost:8181/restconf/operations/ocp-service:create-obj-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objType | String | Object type | RxSigPath_5G | Yes |
name | String | Object parameter name | dataLink | No |
value | String | Object parameter value | dataLink:1 | No |
Example.
{
"create-obj-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objType": "RxSigPath_5G",
"param": [
{
"name": "dataLink",
"value": "dataLink:1"
}
]
}
}
}
Field Name | Type | Description |
---|---|---|
objId | String | Object ID |
globResult | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJTYPE”, “FAIL_STATIC_OBJTYPE”, “FAIL_UNKNOWN_OBJECT”, “FAIL_CHILD_NOTALLOWED”, “FAIL_OUTOF_RESOURCES” “FAIL_PARAMETER_FAIL”, “FAIL_NOSUCH_RESOURCE” |
name | String | Object parameter name |
result | String, enumerated | “SUCCESS”, “FAIL_UNKNOWN_PARAM”, “FAIL_PARAM_READONLY”, “FAIL_PARAM_LOCKREQUIRED”, “FAIL_VALUE_OUTOF_RANGE”, “FAIL_VALUE_TYPE_ERROR” |
Example.
{
"output": {
"objId": "RxSigPath_5G:0",
"globResult": "SUCCESS",
"param": [
{
"name": "dataLink",
"result": "SUCCESS"
}
]
}
}
The Object Deletion procedure allows the application to delete a given object instance and recursively its entire child objects on the RE.
Default URL: http://localhost:8181/restconf/operations/ocp-service:delete-obj-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RxSigPath_5G:1 | Yes |
Example.
{
"delete-obj-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"obj-id": "RxSigPath_5G:0"
}
}
}
Field Name | Type | Description |
---|---|---|
result | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_STATIC_OBJTYPE”, “FAIL_LOCKREQUIRED” |
Example.
{
"output": {
"result": "SUCCESS"
}
}
The Object State Reporting procedure allows the application to acquire the current state (for the requested state type) of one or more objects of the RE resource model, and additionally configure event-triggered reporting of the detected state changes for all state types of the indicated objects.
Default URL: http://localhost:8181/restconf/operations/ocp-service:get-state-nb
Field Name | Type | Description | Example | Required ? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RxSigPath_5G:1 | Yes |
stateType | String, enumerat ed | Valid values: “AST”, “FST”, “ALL” | ALL | Yes |
eventDrivenReporti ng | Boolean | Event-triggered reporting of state change | true | Yes |
Example.
{
"get-state-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objId": "antPort:0",
"stateType": "ALL",
"eventDrivenReporting": "true"
}
}
}
Field Name | Type | Description |
---|---|---|
id | String | Object ID |
type | String, enumerated | State type. Valid values: “AST”, “FST |
value | String, enumerated | State value. Valid values: For state type = “AST”: “LOCKED”, “UNLOCKED”. For state type = “FST”: “PRE_OPERATIONAL”, “OPERATIONAL”, “DEGRADED”, “FAILED”, “NOT_OPERATIONAL”, “DISABLED” |
result | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_UNKNOWN_STATETYPE”, “FAIL_VALUE_OUTOF_RANGE” |
Example.
{
"output": {
"obj": [
{
"id": "antPort:0",
"state": [
{
"type": "FST",
"value": "DISABLED"
},
{
"type": "AST",
"value": "LOCKED"
}
]
}
],
"result": "SUCCESS"
}
}
The Object State Modification procedure allows the application to trigger a change in the state of an object of the RE Resource Model.
Default URL: http://localhost:8181/restconf/operations/ocp-service:modify-state-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RxSigPath_5G:1 | Yes |
stateType | String, enumerated | Valid values: “AST”, “FST”, “ALL” | AST | Yes |
stateValue | String, enumerated | Valid values: For state type = “AST”: “LOCKED”, “UNLOCKED”. For state type = “FST”: “PRE_OPERATIONAL”, “OPERATIONAL”, “DEGRADED”, “FAILED”, “NOT_OPERATIONAL”, “DISABLED” | LOCKED | Yes |
Example.
{
"modify-state-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objId": "RxSigPath_5G:1",
"stateType": "AST",
"stateValue": "LOCKED"
}
}
}
Field Name | Type | Description |
---|---|---|
objId | String | Object ID |
stateType | String, enumerated | State type. Valid values: “AST”, “FST |
stateValue | String, enumerated | State value. Valid values: For state type = “AST”: “LOCKED”, “UNLOCKED”. For state type = “FST”: “PRE_OPERATIONAL”, “OPERATIONAL”, “DEGRADED”, “FAILED”, “NOT_OPERATIONAL”, “DISABLED” |
result | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_UNKNOWN_STATETYPE”, “FAIL_UNKNOWN_STATEVALUE”, “FAIL_STATE_READONLY”, “FAIL_RESOURCE_UNAVAILABLE”, “FAIL_RESOURCE_INUSE”, “FAIL_PARENT_CHILD_CONFLICT”, “FAIL_PRECONDITION_NOTMET |
Example.
{
"output": {
"objId": "RxSigPath_5G:1",
"stateType": "AST",
"stateValue": "LOCKED",
"result": "SUCCESS",
}
}
The Fault Reporting procedure allows the application to acquire information about all current active faults associated with a primary object, as well as configure the RE to report when the fault status changes for any of faults associated with the indicated primary object.
Default URL: http://localhost:8181/restconf/operations/ocp-service:get-fault-nb
Field Name | Type | Description | Example | Required? |
---|---|---|---|---|
nodeId | String | Inventory node reference for OCP radio head | ocp:MTI-101-200 | Yes |
objId | String | Object ID | RE:0 | Yes |
eventDrive nReporting | Boolean | Event-triggered reporting of fault | true | Yes |
Example.
{
"get-fault-nb": {
"input": {
"nodeId": "ocp:MTI-101-200",
"objId": "RE:0",
"eventDrivenReporting": "true"
}
}
}
Field Name | Type | Description |
---|---|---|
result | String, enumerated | Common default result codes + “FAIL_UNKNOWN_OBJECT”, “FAIL_VALUE_OUTOF_RANGE” |
id (obj) | String | Object ID |
id (fault) | String | Fault ID |
severity | String | Fault severity |
timestamp | dateTime | Time stamp |
descr | String | Text description |
affectedObj | String | Affected object |
Example.
{
"output": {
"result": "SUCCESS",
"obj": [
{
"id": "RE:0",
"fault": [
{
"id": "FAULT_OVERTEMP",
"severity": "DEGRADED",
"timestamp": "2012-02-12T16:35:00",
"descr": "PA temp too high; Pout reduced",
"affectedObj": [
"TxSigPath_EUTRA:0",
"TxSigPath_EUTRA:1"
]
},
{
"id": "FAULT_VSWR_OUTOF_RANGE",
"severity": "WARNING",
"timestamp": "2012-02-12T16:01:05",
}
]
}
],
}
}
Note
The northbound APIs described above wrap the southbound APIs to make them accessible to external applications via RESTCONF, as well as take care of synchronizing the RE resource model between radio heads and the controller’s datastore. See applications/ocp-service/src/main/yang/ocp-resourcemodel.yang for the yang representation of the RE resource model.
The southbound APIs provide concrete implementation of the following OCP elementary functions: health-check, set-time, re-reset, get-param, modify-param, create-obj, delete-obj, get-state, modify-state and get-fault. Any OpenDaylight services/applications (of course, including OCP service) wanting to speak OCP to radio heads will need to use them.
Interface SalDeviceMgmtService defines three methods corresponding to health-check, set-time and re-reset.
SalDeviceMgmtService.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
public interface SalDeviceMgmtService
extends
RpcService
{
Future<RpcResult<HealthCheckOutput>> healthCheck(HealthCheckInput input);
Future<RpcResult<SetTimeOutput>> setTime(SetTimeInput input);
Future<RpcResult<ReResetOutput>> reReset(ReResetInput input);
}
Interface SalConfigMgmtService defines two methods corresponding to get-param and modify-param.
SalConfigMgmtService.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.config.mgmt.rev150811;
public interface SalConfigMgmtService
extends
RpcService
{
Future<RpcResult<GetParamOutput>> getParam(GetParamInput input);
Future<RpcResult<ModifyParamOutput>> modifyParam(ModifyParamInput input);
}
Interface SalObjectLifecycleService defines two methods corresponding to create-obj and delete-obj.
SalObjectLifecycleService.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.lifecycle.rev150811;
public interface SalObjectLifecycleService
extends
RpcService
{
Future<RpcResult<CreateObjOutput>> createObj(CreateObjInput input);
Future<RpcResult<DeleteObjOutput>> deleteObj(DeleteObjInput input);
}
Interface SalObjectStateMgmtService defines two methods corresponding to get-state and modify-state.
SalObjectStateMgmtService.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
public interface SalObjectStateMgmtService
extends
RpcService
{
Future<RpcResult<GetStateOutput>> getState(GetStateInput input);
Future<RpcResult<ModifyStateOutput>> modifyState(ModifyStateInput input);
}
Interface SalFaultMgmtService defines only one method corresponding to get-fault.
SalFaultMgmtService.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
public interface SalFaultMgmtService
extends
RpcService
{
Future<RpcResult<GetFaultOutput>> getFault(GetFaultInput input);
}
In addition to indication messages, the OCP southbound plugin will translate specific events (e.g., connect, disconnect) coming up from the OCP protocol library into MD-SAL Notification objects and then publish them to the MD-SAL. Also, the OCP service will notify the completion of certain operation via Notification as well.
An onDeviceConnected Notification will be published to the MD-SAL as soon as a radio head is connected to the controller, and when that radio head is disconnected the OCP southbound plugin will publish an onDeviceDisconnected Notification in response to the disconnect event propagated from the OCP protocol library.
SalDeviceMgmtListener.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.device.mgmt.rev150811;
public interface SalDeviceMgmtListener
extends
NotificationListener
{
void onDeviceConnected(DeviceConnected notification);
void onDeviceDisconnected(DeviceDisconnected notification);
}
The OCP service will publish an onAlignmentCompleted Notification to the MD-SAL once it has completed the OCP alignment procedure with the radio head.
OcpServiceListener.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.params.xml.ns.yang.ocp.applications.ocp.service.rev150811;
public interface OcpServiceListener
extends
NotificationListener
{
void onAlignmentCompleted(AlignmentCompleted notification);
}
When receiving a state change indication message, the OCP southbound plugin will propagate the indication message to upper layer services/applications by publishing a corresponding onStateChangeInd Notification to the MD-SAL.
SalObjectStateMgmtListener.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.object.state.mgmt.rev150811;
public interface SalObjectStateMgmtListener
extends
NotificationListener
{
void onStateChangeInd(StateChangeInd notification);
}
When receiving a fault indication message, the OCP southbound plugin will propagate the indication message to upper layer services/applications by publishing a corresponding onFaultInd Notification to the MD-SAL.
SalFaultMgmtListener.java.
package org.opendaylight.yang.gen.v1.urn.opendaylight.ocp.fault.mgmt.rev150811;
public interface SalFaultMgmtListener
extends
NotificationListener
{
void onFaultInd(FaultInd notification);
}