e2.md

E2 API

The github.com/onosproject/onos-ric-sdk-go/pkg/e2/v1beta1 provides a high-level interface for interacting with E2 nodes. The current interface supports E2AP Subscription and Control procedures.

Creating An E2 Client

To create an E2 client, the following information should be specified:

• Service model name and its version
• E2T address
• Encoding type (e.g. Protobuf or ASN.1 PER encoding)

For example, the following code snippet shows how to create an E2 client for KPM v2 service model:

import (
   e2client "github.com/onosproject/onos-ric-sdk-go/pkg/e2/v1beta1
)


// Defines service model name and version to be used for creating an  E2 client. 
// For example, to create an E2 client for kpm v2 service model, the following service model name and version should be used:
const (
	serviceModelName := "oran-e2sm-kpm"
	serviceModelVersion := "v2"
)


client := e2client.NewClient(e2client.WithE2TAddress("onos-e2t", 5150), 
  	        e2client.WithServiceModel(e2client.ServiceModelName(serviceModelName), 
  		e2client.ServiceModelVersion(serviceModelVersion)), 
  		e2client.WithEncoding(e2client.ProtoEncoding)

E2 Subscription API

To subscribe for receiving indications from an E2 node, first create an instance of E2 node using E2 node ID (i.e. the ID which is used to create E2 node entity in onos-topo), and define a subscription spec. A Subscription spec should specify the following items:

• Service model specific actions
• Service model specific event triggers

For example, the following code snippet, creates a subscription spec for KPM v2 service model that requires specifying a report action including Action Definition and Event Triggers encoded data.

import (
    e2api "github.com/onosproject/onos-api/go/onos/e2t/e2/v1beta1"
)  
   ...

   e2node := client.Node(e2client.NodeID(e2nodeID))
   subName := "onos-kpimon-subscription" // A unique and constant subscription name
   var eventTriggerData []byte     // Encode the service model specific event trigger
   var actionDefinitionData []byte // Encode the service model specific Action Definitions 
   var actions []e2api.Action
   action := e2api.Action{
    ID:   100,
    Type: e2api.ActionType_ACTION_TYPE_REPORT,
    SubsequentAction: &e2api.SubsequentAction{
        Type:       e2api.SubsequentActionType_SUBSEQUENT_ACTION_TYPE_CONTINUE,
        TimeToWait: e2api.TimeToWait_TIME_TO_WAIT_ZERO,
   },
    Payload: actionDefinitionData, 
   }
   
   
   subSpec := e2api.SubscriptionSpec{
        Actions: actions,     
        EventTrigger: e2api.EventTrigger{
             Payload: eventTriggerData,  
     },
} 

Once the subscription spec is defined, use the Subscribe method to register the subscription and begin receiving indications. Indications are received in a Go channel:

ch := make(chan e2api.Indication)

channelID, err := e2node.Subscribe(context.TODO(), subName, subSpec, ch)
if err != nil {
   return err
}

for ind := range ch {
    ...
}

The Subscribe method will return once the subscription has been registered with the subscription service. Once a subscription has been registered, it will not be unregistered until explicitly requested by the client. Changes to the state of the E2 node, subscription service, and termination points will be handled transparently by the core services and client implementation, which will work continuously to receive indications on the given channel.

A context.Context can be used to set a timeout for the subscription initialization:

ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
channelID, err := e2node.Subscribe(ctx, subName, subSpec, ch)

To unsubscribe a registered subscription:

err = node.Unsubscribe(ctx, subName)
if err != nil {
	return err
}

E2 Control API

Control API providing the capability of sending E2 control messages to the E2 node via E2T and receiving E2AP control acknowledgement and failure messages.

To use control API, the following package should be imported in your go code

 e2api "github.com/onosproject/onos-api/go/onos/e2t/e2/v1beta1"

Follow the instructions in Creating an E2 Client section to create an E2 client for a service model that supports E2AP Control API(i.e. change the service model name and version to the corresponding service model, e.g. serviceModelName = "oran-e2sm-rc-pre", serviceModelVersion = "v2")

After creating the client, a control message should be created which has the following items:

• Header: service model specific control header bytes
• Payload: service model specific control message bytes

For example, to send a control message to an E2 node:

controlMessage := &e2api.ControlMessage {
	Header: header,
	Payload: payload,
}

node := e2client.Node(e2client.NodeID(e2nodeID))
outcome, err := node.Control(ctx, controlMessage)

The return value of Control method is an error or service model specific control outcome bytes that should be decoded using service models to extract control outcome information.