-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 110.
+
+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)