From c2a39f5c22d1f0e89791e4e48917c010420f4c28 Mon Sep 17 00:00:00 2001
From: Andrew Zaborowski <andrew.zaborowski@intel.com>
Date: Sat, 20 May 2017 01:39:39 +0200
Subject: [PATCH] doc: SignalLevelAgent related docs

---
 doc/device-api.txt             | 30 ++++++++++++++++++++++++++++++
 doc/signal-level-agent-api.txt | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 doc/signal-level-agent-api.txt

diff --git a/doc/device-api.txt b/doc/device-api.txt
index c135e433..1bf30b89 100644
--- a/doc/device-api.txt
+++ b/doc/device-api.txt
@@ -56,6 +56,36 @@ Methods		void Scan()
 				Contains the type of the network.  Possible
 				types are "open", "psk", "8021x" (EAP)
 
+		void RegisterSignalLevelAgent(object path,
+						 array(int16) levels)
+
+			Register the agent object to receive signal strength
+			level change notifications on the
+			net.connman.iwd.SignalLevelAgent interface, see
+			signal-level-agent-api.txt.  The "levels"
+			parameters decides the thresholds in dBm that will
+			generate a call to the agent's SignalLevelChanged
+			method whenever current RSSI crosses any of the
+			values.  The values must be passed in descending
+			order.  The number and distance between requested
+			threshold values is a compromise between resolution
+			and the frequency of system wakeups and
+			context-switches that are going to be occuring to
+			update the client's signal meter.  Only one agent
+			can be registered at any time.
+
+			Possible Errors: [service].Error.InvalidArguments
+					 [service].Error.Failed
+					 [service].Error.AlreadyExists
+					 [service].Error.NotSupported
+
+		void UnregisterSignalLevelAgent(object path)
+
+			Unregister an existing agent.
+
+			Possible Errors: [service].Error.InvalidArguments
+					 [service].Error.NotFound
+
 Properties	string Name [readonly]
 
 			Device's interface name
diff --git a/doc/signal-level-agent-api.txt b/doc/signal-level-agent-api.txt
new file mode 100644
index 00000000..59f37613
--- /dev/null
+++ b/doc/signal-level-agent-api.txt
@@ -0,0 +1,33 @@
+SignalLevelAgent hierarchy
+==========================
+
+Service		unique name
+Interface	net.connman.iwd.SignalLevelAgent
+Object path	freely definable
+
+Methods		void Release(object device)
+
+			This method gets called when the service daemon
+			unregisters the agent. An agent can use it to do
+			cleanup tasks. There is no need to unregister the
+			agent, because when this method gets called it has
+			already been unregistered.
+
+		string SignalLevelChanged(object device, uint8 level)
+
+			This method gets called when the signal strength
+			measurement for the device's connected network
+			changes enough to go from one level to another out
+			of the N ranges defined by the array of (N-1)
+			threshold values passed to
+			net.connman.iwd.Device.RegisterSignalLevelAgent
+			(see device-api.txt.)  The level parameter is in
+			the range from 0 to N, 0 being the strongest
+			signal or above the first threshold value in the
+			array, and N being the weakest and below the
+			last threshold value.  For example if
+			RegisterSignalLevelAgent was called with the
+			array [-40, -50, -60], the 'level' parameter of
+			0 would mean signal is received at -40 or more dBm
+			and 3 would mean below -60 dBm and might correspond
+			to 1 out of 4 bars on a UI signal meter.