X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Falarm_api.rst;h=87b7914d9740a25d89be7bb21571a406622fd7ac;hb=c1c457c3601bfda6735b39915fa44a3b5dcc8db0;hp=0e7b2620ab7be35b38957920d1e1605814bfedbc;hpb=6d71c1e54654b77eeab54d8a87af99fb71c8520c;p=ric-plt%2Fxapp-frame-py.git

diff --git a/docs/alarm_api.rst b/docs/alarm_api.rst
index 0e7b262..87b7914 100644
--- a/docs/alarm_api.rst
+++ b/docs/alarm_api.rst
@@ -8,22 +8,52 @@ RIC Alarm API
 Overview
 --------
 
-The xapp python framework package includes a python subpackage called
-`Alarm`.  This subpackage (`ricxappframe.alarm`) provides objects and
-methods for defining and raising alarms, which are transmitted using
-the RMR shared library.
+The xapp python framework provides an alarm feature in the python
+subpackage `ricxappframe.alarm`.  This subpackage defines objects and
+methods for creating, raising and clearing alarms.
 
-Usage of this python package requires that the RMR shared-object
-library is installed in a system library that is included in the
-directories found by default, usually something like /usr/local/lib.
+The alarm feature reuses the `ricxappframe.rmr` subpackage for
+transporting alarm messages. That in turn requires the RMR
+shared-object library to be available in a system library that is
+searched by default, usually something like /usr/local/lib.
+
+The alarm feature sends messages using RMR message type
+`RIC_ALARM_UPDATE` in the `ricxappframe.alarm.alarm` module, currently
+value 13111. The Xapp's routing table must have one (or more) entries
+for that message type.
+
+The complete API for the Alarm feature appears below.
+
+
+Example Usage
+-------------
+
+Alarms are created, raised and cleared using an `AlarmManager` as
+shown below. The manager requires an RMR context at creation time.
+
+.. code-block:: python
+
+    from ricxappframe.alarm import alarm
+    from ricxappframe.rmr import rmr
+
+    rmr_context = rmr.rmr_init(b"4562", rmr.RMR_MAX_RCV_BYTES, 0x00)
+    alarm_mgr = alarm.AlarmManager(rmr_context, "managed-object-id", "application-id")
+    alarm3 = alarm_mgr.create_alarm(3, alarm.AlarmSeverity.DEFAULT, "identifying", "additional")
+    success = alarm_mgr.raise_alarm(alarm3)
 
-Alarm messages conform to the following JSON schema.
 
-.. literalinclude:: ../ricxappframe/alarm/alarm-schema.json
-  :language: JSON
 
 Alarm API
 ---------
 
 .. automodule:: ricxappframe.alarm.alarm
     :members:
+
+
+Alarm Messages
+--------------
+
+Alarm messages conform to the following JSON schema.
+
+.. literalinclude:: ../ricxappframe/alarm/alarm-schema.json
+  :language: JSON