Go SDK Signatures

Overview

The Go SDK and the Python SDK signatures are both based on the C SDK, utilizing the SWIG wrapper for adaption. They facilitate the full lifecycle management of an xApp in Go. Initially, the table below offers an overview of each signature, with a comprehensive description of each to follow in the subsequent Detail of Signatures section.

Signature	Description
`Init()`	Initializes the xApp and sends an `E42-Setup-Request` to NearRT-RIC based on the given configurations
`Get_cust_sm_conf()`	Get customized service model configurations (e.g., service model name, subscription period) read from the xApp configuration file
`Get_oran_sm_conf)`	Get O-RAN standarized service model configurations (e.g., service model name, subscription period, and action definitions) read from the xApp configuration file
`Conn_e2_nodes()`	Get connected E2-Nodes' information (e.g., NodeB ID, RAN type and supported RAN functions, etc)
`Report_{SM-NAME}_sm()`	Sends a `RIC-Subscription-Request` to subscribe the RAN function on the specific E2-Node via the service model
`({SM-NAME}Callback)Handle()`	A method defined on {SM-Name}Callback struct to handle indication messages received by the xApp
`Control_{SM-NAME}_sm()`	Sends a `RIC-Conctrol-Request` to the RAN function at the specific E2-Node via the service model
`Rm_report_{SM-NAME}_sm()`	Sends a `RIC-Delete-Subscription-Request` to unsubscribes the subscribed RAN functions
`Try_stop()`	Terminates the xApp

Note: {SM-NAME} serves as a placeholder for the name of a specific service model, for example: if {SM-NAME} = kpm which stands for Key Performance Measurement service model, the function names will be report_kpm_sm, sm_kpm_rc, KPMCallback() and so on. The supported {SM-NAME}s in Python SDK include:

Customized service models: mac, rlc, pdcp, gtp, slice

O-RAN standarized service models: kpm

Sequence Diagram

The following figures illustrates the sequence diagram of lifecycle in a Go xApp, including:

Init: initialize xApp (from step 2 to 11)
Report Service: subscribe RAN function via service model (from step 12 to 20)
xApp Logic: store or process receiving data from RAN functions (from step 21 to 23)
Control Service: control RAN function via service model (from step 24 to 30)
Exit: termiate xApp (from step 31 to 41)

This helps us understand what is the role of each signature and when it should be used.

Detail of Signatures

Init - Step 2 to 11

Used functions

`Init()`

Example:

package main

// import Go SDK
import (
  xapp "build/examples/xApp/go/xapp_sdk"
)

// Call init function and give command-line arguments as input
// Note: Since the type of os.Args is []string, 
// it has be converted to xapp_sdk.SwigcptrStringVector by using the function xapp.SlToStrVec() before being passed in.
sysArgs := xapp.SlToStrVec(os.Args)
xapp.Init(sysArgs)

Input:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`sysArgs`	`xapp_sdk.SwigcptrStringVector`	`vector<string>& argv`	This parameter captures all the command-line arguments, including any options and their respective values

Output: N/A

`Get_cust_sm_conf()`

Example:

// Get customized SMs' configurations
cust_sm := xapp.Get_cust_sm_conf()

// Loop cust_sm to get each SM confiugration object
for j := 0; j < int(cust_sm.Size()); j++ {
    // Get object for the current service model 
    smInfo := cust_sm.Get(j)
    
    // Get name
    smName := smInfo.GetName()

    // Get time
    smTime := smInfo.GetTime()
    // Convert type of time from string to xapp_sdk.Interval for subscription function
    tti := get_cust_tti(smTime)
}

Input: N/A

Output:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`cust_sm`	`xapp_sdk.SwigcptrSwigSubCustSmVector`	`vector<swig_sub_cust_sm_t>`	This parameter contains the configured customized service models' information read from `Sub_CUST_SM_List` in xApp configuration file (e.g., xapp.conf)

`Get_oran_sm_conf()`

Example:

// Get O-RAN standarized SMs' configurations
oran_sm := xapp.Get_oran_sm_conf()

// Loop oran_sm to get each SM confiugration object
for j := 0; j < int(oran_sm.Size()); j++ {
    // Get object for the current service model 
    smInfo := oran_sm.Get(j)

    // Get name
    smName := smInfo.GetName()

    // Get time
    smTime := smInfo.GetTime()
    // Convert type of time from string to xapp_sdk.Interval for subscription function
    tti := get_oran_tti(smTime)

    // Get foramt of action definition
    format := smInfo.GetFormat()

    // Get RAN type
    ranType := smInfo.GetRan_type()
    
    // Get configured meauremnet names
    actions := smInfo.GetActions()

    // Store the configured meauremnet names in a []string to create action definition in SWIG level
    var actionSlice []string
    for a := 0; a < int(actions.Size()); a++ {
        act_name_id := actions.Get(a)
        actName := act_name_id.GetName()
        actionSlice = append(actionSlice, actName)
    }
}

Input: N/A

Output:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`oran_sm`	`xapp_sdk.SwigcptrSwigSubOranSmVector`	`vector<swig_sub_oran_sm_t>`	This parameter contains the configured O-RAN standarized service models' information read from `Sub_ORAN_SM_List` in xApp configuration file

`Conn_e2_nodes()`

Example:

// Get connected E2-Nodes
var conn xapp.E2NodeVector = xapp.Conn_e2_nodes()

// Case 1: if no E2-Node connected, do no excuting xApp anymore
if conn.Size() <= 0 {
    panic(fmt.Sprintf("panic"))
}

// Case 2: if the number of connected E2-Nodes is greater than 0
// Loop nodes to get each connected E2-Node' information
for i := int64(0); i < conn.Size(); i++ {
    // Get object for the current E2-Node
    e2Node := conn.Get(int(i))

    // Get NodeB ID
    nb_id := e2Node.GetId().GetNb_id().GetNb_id()
    
    // Get PLMN
    plmn_mcc = e2Node.GetId().GetPlmn().GetMcc()
    plmn_mnc = e2Node.GetId().GetPlmn().GetMnc()
    
    // Get RAN type
    e2node_type = e2Node.GetId().GetXtype()
    
    // Check the configured RAN type is the same as the connceted E2-Node's RAN type
    // Note: configured_ran_type is read from the xApp configuration file
    if configured_ran_type == xapp.Get_e2ap_ngran_name(e2node_type) {
      // do somthing, i.e., send subscription request
    }    
}
    

Input: N/A

Output:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`conn`	`xapp.E2NodeVector`	`vector<E2Node>`	This parameter contains the connected E2-Nodes' information, including globle E2-Node ID and RAN function definitions

Report Service - Step 12 to 20

Used functions
- Report_{SM-NAME}_sm()

`Report_{SM-NAME}_sm()`

Example - Customized SM: {SM-NAME} = mac

// Define a handler to save the RIC Request ID
var handleMAC []int

// Subscribe MAC RAN functions on all the connected E2-Nodes
for i := 0; i < int(conn.Size()); i++ {
    // define a callback for MAC SM
    innerMac := MACCallback{}
    callbackMac := xapp.NewDirectorMac_cb(innerMac)
    
    // Send subscription request to conn.Get(int(i)) by giving:
    // global E2-Node ID, transmission time intervale of indicaiton message, and defined callback function
    hndlr := xapp.Report_mac_sm(conn.Get(int(i)).GetId(), tti, callbackMac)
    
    // Append the RIC Request ID
    handleMAC = append(handleMAC, hndlr)
}

Input:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`conn.Get(int(i)).GetId()`	`xapp_sdk.SwigcptrSwig_global_e2_node_id_t`	`swig_global_e2_node_id_t*`	Stands for Global E2-Node ID
`tti`	`xapp_sdk.Interval`	`Interval`	Time duration of each RIC Indication read from xapp.conf
`callbackMac`	`*xapp_sdk._swig_DirectorMac_cb`	`mac_cb*`	Defined callback function in xApp

Output:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`hndlr`	`int`	`int`	RIC Request ID

Example - O-RAN Standarized SM: {SM-NAME} = kpm

// Define a handler to save the RIC Request ID
var handleKPM []int

// Subscribe KPM RAN functions on all the connected E2-Nodes
for i := int64(0); i < conn.Size(); i++ {
    // define a callback for KPM SM
    inner := KPMCallback{}
    callbackKpm := xapp.NewDirectorKpm_cb(inner)
  
    // Send subscription request to conn.Get(int(i)) by giving:
    // global E2-Node ID, transmission time intervale of indicaiton message,
    // list of measurment names, and defined callback function
    act := xapp.SlToStrVec(actionSlice)
    hndlr := xapp.Report_kpm_sm(conn.GetId(), tti, act, callbackKpm)
  
    // Append the RIC Request ID
    handleKPM = append(handleKPM, hndlr)
}

Input:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`conn.Get(int(i)).GetId()`	`xapp_sdk.SwigcptrSwig_global_e2_node_id_t`	`swig_global_e2_node_id_t*`	Stands for Global E2-Node ID
`tti`	`xapp_sdk.Interval`	`Interval`	Time duration of each RIC Indication read from xapp.conf
`act`	`xapp_sdk.SwigcptrStringVector`	`vector<string>& action*`	List of measurement names read from xapp.conf
`callbackKpm`	`*xapp_sdk._swig_DirectorKpm_cb`	`kpm_cb*`	Defined callback function in xApp

Output:

Parameter Type in Go Type in Swig Wrapper C++ Comment
hndlr int int RIC Request ID

xApp Logic - Step 21 to 23

Used functions
- ({SM-NAME}Callback)Handle()

`({SM-NAME}Callback)Handle()`

Example - O-RAN standarized SM: {SM-NAME} = kpm

// Define an empty struct which serves as a placeholder for implementing methods associated with KPM callbakc functionalities
type KPMCallback struct {
}

// Deinfe a method on the KPMCallback struct, and it takes type xapp.Swig_kpm_ind_data_t as input
func (kpm_cb KPMCallback) Handle(ind xapp.Swig_kpm_ind_data_t) {
  if ind.GetHdr() != nil {
  	tNow := time.Now().UnixNano() / 1000
  	tKpm := int64(ind.GetHdr().GetKpm_ric_ind_hdr_format_1().GetCollectStartTime()) / 1
  	tDiff := float64(tNow-tKpm)

  	fmt.Printf("KPM Indication tstamp %d diff %.3f E2-node type %d nb_id %d\n",
  		tNow, tDiff, ind.GetId().GetXtype(), ind.GetId().GetNb_id().GetNb_id())
  }
}

Input of Handle():

Parameter Type in Go Type in Swig Wrapper C++ Comment
ind xapp.Swig_kpm_ind_data_t swig_kpm_ind_data_t* A RIC Indication message storing data in swig_kpm_ind_data_t

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`ind`	`xapp.Swig_kpm_ind_data_t`	`swig_kpm_ind_data_t*`	A RIC Indication message storing data in `swig_kpm_ind_data_t`

Note: Once the RIC Subscription Request is received by the E2-Node, the xApp will continue to receive RIC Indications forwarded from the C SDK to the Go SDK via Handle(). For further development (i.e., ML or AI usage), developers can process the received RIC Indications to analyze/optimize network performance.

Control Service - Step 24 to 30

Used functions
- Control_{SM-NAME}_sm()

`Control_{SM-NAME}_sm()`

Example - Customized SM: {SM-NAME} = slice

// Create slice control message by following the structure slice_ctrl_msg_t
msg := FillSliceCtrlMsg()

// Send control request to conn.Get(int(i)) by giving:
// global E2-Node ID and predefined contorl message
xapp.Control_slice_sm(conn.Get(int(i)).GetId(), msg)

Input:

Parameter	Type in Go	Type in Swig Wrapper C++	Comment
`conn.Get(int(i)).GetId()`	`xapp_sdk.SwigcptrSwig_global_e2_node_id_t`	`swig_global_e2_node_id_t*`	Stands for Global E2-Node ID
`msg`	`xapp_sdk.SwigcptrSlice_ctrl_msg_t`	`slice_ctrl_msg_t*`	Control message written by xApp

Output: N/A

Exit - Step 31 -41

Used functions
- Rm_report_{SM-NAME]_sm()
- Try_stop()

`Rm_report_{SM-NAME]_sm()`

Example - Customized SM: {SM-NAME} = mac

// Loop list of handler to send subcription delete request to each recorded RIC Request ID
for _, hndlr := range handleMAC {
  	xapp.Rm_report_mac_sm(hndlr)
}

Input:

Parameter Type in Python Type in Swig Wrapper C++ Comment
hndlr int int RIC Request ID
Output: N/A

`Try_stop()`

Example - Customized SM: {SM-NAME} = mac

// Call the stop function every one second until it recevies a true value
ans := xapp.Try_stop()
for ans == false {
    time.Sleep(1 * time.Second)
    ans = xapp.Try_stop()
}

Input: N/A

Output:

Parameter	Type in Python	Type in Swig Wrapper C++	Comment
`ans`	`bool`	`bool`	The status of terminating an xApp: "TRUE" means the xApp has terminated completely, including freeing the memory; "FALSE" indicates the opposite.

Overview​

Sequence Diagram​

Detail of Signatures​

Init - Step 2 to 11​

Init()​

Get_cust_sm_conf()​

Get_oran_sm_conf()​

Conn_e2_nodes()​

Report Service - Step 12 to 20​

Report_{SM-NAME}_sm()​

xApp Logic - Step 21 to 23​

({SM-NAME}Callback)Handle()​

Control Service - Step 24 to 30​

Control_{SM-NAME}_sm()​

Exit - Step 31 -41​

Rm_report_{SM-NAME]_sm()​

Try_stop()​

Overview

Sequence Diagram

Detail of Signatures

Init - Step 2 to 11

`Init()`

`Get_cust_sm_conf()`

`Get_oran_sm_conf()`

`Conn_e2_nodes()`

Report Service - Step 12 to 20

`Report_{SM-NAME}_sm()`

xApp Logic - Step 21 to 23

`({SM-NAME}Callback)Handle()`

Control Service - Step 24 to 30

`Control_{SM-NAME}_sm()`

Exit - Step 31 -41

`Rm_report_{SM-NAME]_sm()`

`Try_stop()`