X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=README.md;h=7a0cccc04ecf4a162c8a6b73d0c9c194181f3370;hb=749726bcd7bd058ac425dd260f701a961c2d5210;hp=e5d6f0fa724b3e3ab1e03cd23857b07264ef4a64;hpb=b980c9a06fbc11dab51305e9650b49a13ea1d142;p=ric-plt%2Fxapp-frame.git

diff --git a/README.md b/README.md
index e5d6f0f..7a0cccc 100755
--- a/README.md
+++ b/README.md
@@ -18,44 +18,135 @@
 * Encoding and decoding of commonly used RIC ASN.1 messages
 * And more to come
 
+## Prerequisites
+Make sure that following tools are properly installed and configured
+* GO (golang) development and runtime tools
+* MDCLOG (ricplt/com/log)
+* RMR (ricplt/lib/rmr)
+* DBAAS (redis-server)
+
 ## Quick Start
 
 #### Below is a simple example xapp. For more information, see the sample code in the xapp/examples folder:
 ```go
 package main
 
-import "gitlabe1.ext.net.nokia.com/ric_dev/nokia-xapps/xapp/pkg/xapp"
+import "gerrit.o-ran-sc.org/r/ric-plt/xapp-frame/pkg/xapp"
 
-type MessageCounsumer struct {
+type ExampleXapp struct {
 }
 
-func (m MessageCounsumer) Consume(mtype, len int, payload []byte) (err error) {
-        xapp.Logger.Debug("Message received - type=%d len=%d", mtype, len)
+func (m *ExampleXapp) Consume(rp *xapp.RMRParams) (err error) {
+        xapp.Logger.Debug("Message received - type=%d len=%d", rp.Mtype, rp.PayloadLen)
 
-        xapp.Sdl.Store("myKey", payload)
-        xapp.Rmr.Send(10005, len, payload)
+        xapp.Sdl.Store("myKey", rp.Payload)
+        xapp.Rmr.Send(r)
         return nil
 }
 
 func main() {
-    xapp.Run(MessageCounsumer{})
+       xapp.Run(ExampleXapp{})
 }
 ```
-#### Installing and running the example xapp
+#### Building and running the example xapp
+
+    git clone https://gerrit.o-ran-sc.org/r/ric-plt/xapp-frame
+    cd xapp-frame
+
+#### To generate an executable binary for our sample xApp application, run the following command:
+
+    GO111MODULE=on GO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o example-xapp examples/example-xapp.go
 
-    git clone git@gitlabe1.ext.net.nokia.com:ric_dev/nokia-xapps/xapp.git
+#### To run the generated executable binary locally, run the following command:
 
-#### Build and run
-    unset GOPATH
-    cd xapp/examples
-    go build example-xapp.go
-    ./example-xapp
+    RMR_SEED_RT=config/uta_rtg.rt ./example-xapp -f config/config-file.yaml
 
 Congratulations! You've just built your first **xapp** application.
 
-## API
-#### API List
- * TBD
+## API LIST
+#### Logging APIs
+ * SetLevel(level int)
+  ```
+  Sets logging level to given "level". Level can be 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG
+  ```
+ * SetMdc(key string, value string)
+  ```
+  Sets the application MDC to given string. The MDC will be visible in the logs
+  ```
+ * Error(pattern string, args ...interface{}).
+  ```
+  Writes an error log. Other possible function are: Warn, Info and Debug
+  ```
+
+#### Config APIs
+ * AddConfigChangeListener(f ConfigChangeCB)
+  ```
+  Injects an application callback function that is called when config change occurs
+  ```
+ * GetString(key string) string
+  ```
+  Returns the value associated with the key as a string. Other possible functions are: GetInt, GetBool and GetStringSlice
+  ```
+
+#### Metrics APIs
+ * RegisterCounterGroup(opts []CounterOpts, subsytem string) (c map[string]Counter)
+  ```
+  Creates a new 'Counter' vector based on the provided CounterOpts and partitioned by the given label names.
+  ```
+ * RegisterGaugeGroup(opts []CounterOpts, subsytem string) (c map[string]Gauge)
+  ```
+  Creates a new 'Gauge' vector based on the provided CounterOpts and partitioned by the given label names.
+  ```
+
+#### RMR-client APIs
+ * IsReady() bool
+  ```
+  Indicates whether RMR is ready or not
+  ```
+ * SetReadyCB(cb ReadyCB, params interface{})
+  ```
+  Injects a callback function that is called when RMR is ready
+  ```
+ * Allocate() *C.rmr_mbuf_t
+  ```
+  Allocates and return RMR message buffer
+  ```
+ * Free(mbuf *C.rmr_mbuf_t)
+  ```
+  De-allocates a RMR message buffer previously allocated with 'Allocate'
+  ```
+ * SendMsg(params *RMRParams)
+  ```
+  Sends RMR message based on the given RMR parameters
+  ```
+ * SendRts(params *RMRParams)
+  ```
+  Sends 'rts' RMR message based on the given RMR parameters
+  ```
+
+#### REST APIs
+ * InjectRoute(url string, handler http.HandlerFunc, method string) *mux.Route
+  ```
+  Registers a given URL and corresponding handler, which will be called when incoming request matches with the URL
+  ```
+ * InjectQueryRoute(url string, h http.HandlerFunc, m string, q ...string) *mux.Route
+  ```
+  Registers an inquiry URL and corresponding handler, which will be called when incoming request matches with the URL
+  ```
+ * InjectStatusCb(f StatusCb)
+  ```
+  Injects a callback function, which is called during K8s aliveness probe
+  ```
+
+#### SDL APIs
+ * Store(key string, value interface{}) (err error)
+  ```
+  Store writes the value of a key to SDL. MStore writes multiple key-value pairs atomically
+  ```
+ * Read(key string) (value map[string]interface{}, err error)
+  ```
+  Reads the value of a key from SDL. MRead reads multiple keys atomically
+  ```
 
 #### API Usage and Examples
 * Setting logging level and writing to log
@@ -78,6 +169,24 @@ Congratulations! You've just built your first **xapp** application.
     Resource.InjectQueryRoute("/ric/v1/user", handler, "GET", "foo", "bar", "id", "mykey")
     ```
 
+* Metrics: registering couple of counters
+    ```
+    metrics := []xapp.CounterOpts{
+		{Name: "RICIndicationsRx", Help: "The total number of RIC inidcation events received"},
+		{Name: "RICExampleMessageRx", Help: "The total number of RIC example messages received"},
+	}
+    xapp.Metric.RegisterCounterGroup(metrics, "MyXApp")
+
+    // Use curl-command to get metrics
+    curl http://localhost:8080/ric/v1/metrics
+    ```
+
+## Running unit tests
+  Unit tests of xApp-framework can be run as following:
+  ```
+  make test
+  ```
+
 ## Documentation
 
 ## Community