X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=docs%2Falarm_api.rst;h=0734075f277af22c385b8ae5bbc493881f30c421;hb=a03c517f024363d54865cf75f8e566bb446decf5;hp=0e7b2620ab7be35b38957920d1e1605814bfedbc;hpb=81084bc31ea1d5cde6616dd2267ea01f49a1d6d1;p=ric-plt%2Fxapp-frame-py.git

diff --git a/docs/alarm_api.rst b/docs/alarm_api.rst
index 0e7b262..0734075 100644
--- a/docs/alarm_api.rst
+++ b/docs/alarm_api.rst
@@ -8,22 +8,55 @@ 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 directory that is
+searched by default, usually something like /usr/local/lib.
+
+The alarm feature opens a direct connection to the alarm manager
+using the RMR library's wormhole feature, taking the host name and
+port number from environment variables defined as the constants
+`ALARM_MGR_SERVICE_NAME_ENV` and `ALARM_MGR_SERVICE_PORT_ENV` in
+the `ricxappframe.alarm.alarm` module. The message type is set to
+constant `RIC_ALARM_UPDATE` in the `ricxappframe.alarm.alarm` module,
+currently 13111.
+
+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