Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20200818152612.BlueZ.v1.1.I205718871f4e636958904f3cfb171cfd381c54b1@changeid>
 <20200818152612.BlueZ.v1.7.Iee7e9d13c78dd02c5b283a203dea11a4a4ffa7cc@changeid>
In-Reply-To: <20200818152612.BlueZ.v1.7.Iee7e9d13c78dd02c5b283a203dea11a4a4ffa7cc@changeid>
From:   Luiz Augusto von Dentz <luiz.dentz@gmail.com>
Date:   Tue, 8 Sep 2020 10:39:54 -0700
Message-ID: <CABBYNZLCZ9FCEH=Z3sHzsg-jw_4CvnbMxBNbQem=x0JE_+y7NA@mail.gmail.com>
Subject: Re: [BlueZ PATCH v1 7/7] doc/advertisement-monitor-api: Update
 Advertisement Monitor API description
To:     Miao-chen Chou <mcchou@chromium.org>
Cc:     Bluetooth Kernel Mailing List <linux-bluetooth@vger.kernel.org>,
        Alain Michaud <alainm@chromium.org>,
        Manish Mandlik <mmandlik@chromium.org>,
        Luiz Augusto von Dentz <luiz.von.dentz@intel.com>,
        Howard Chung <howardchung@google.com>
Content-Type: text/plain; charset="UTF-8"
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

Hi Miao,

On Tue, Aug 18, 2020 at 3:34 PM Miao-chen Chou <mcchou@chromium.org> wrote:
>
> This modifies the following description to Advertisement Monitor API.
> - Add org.bluez.Error.Failed to RegisterMonitor() method.
> - Add more description about the usage of RegisterMonitor() and
> UnregisterMonitor() methods.
> - Add description about the ranges for the fields in property
> RSSIThresholdsAndTimers.
>
> Reviewed-by: Yun-Hao Chung <howardchung@google.com>
> Reviewed-by: Manish Mandlik <mmandlik@chromium.org>
> ---
>
>  doc/advertisement-monitor-api.txt | 34 +++++++++++++++++++++++--------
>  1 file changed, 25 insertions(+), 9 deletions(-)
>
> diff --git a/doc/advertisement-monitor-api.txt b/doc/advertisement-monitor-api.txt
> index 74adbfae9..e09b6fd25 100644
> --- a/doc/advertisement-monitor-api.txt
> +++ b/doc/advertisement-monitor-api.txt
> @@ -49,7 +49,7 @@ Properties    string Type [read-only]
>                         org.bluez.AdvertisementMonitorManager1 for the available
>                         options.
>
> -               (Int16, Uint16, Int16, Uint16) RSSIThreshholdsAndTimers [read-only, optional]
> +               (Int16, Uint16, Int16, Uint16) RSSIThresholdsAndTimers [read-only, optional]
>
>                         This contains HighRSSIThreshold, HighRSSIThresholdTimer,
>                         LowRSSIThreshold, LowRSSIThresholdTimer in order. The
> @@ -66,7 +66,11 @@ Properties   string Type [read-only]
>                         RSSIs of the received advertisement(s) during
>                         LowRSSIThresholdTimer do not reach LowRSSIThreshold.
>
> -               array{(uint8, uint8, string)} Patterns [read-only, optional]
> +                       The valid range of a RSSI is -127 to +20 dBm while 127
> +                       dBm indicates unset. The valid range of a timer is 1 to
> +                       300 seconds while 0 indicates unset.
> +
> +               array{(uint8, uint8, array{byte})} Patterns [read-only, optional]
>
>                         If Type is set to 0x01, this must exist and has at least
>                         one entry in the array.
> @@ -80,8 +84,9 @@ Properties    string Type [read-only]
>                                 See https://www.bluetooth.com/specifications/
>                                 assigned-numbers/generic-access-profile/ for
>                                 the possible allowed value.
> -                       string content_of_pattern
> -                               This is the value of the pattern.
> +                       array{byte} content_of_pattern
> +                               This is the value of the pattern. The maximum
> +                               length of the bytes is 31.
>
>  Advertisement Monitor Manager hierarchy
>  =======================================
> @@ -91,20 +96,31 @@ Object path /org/bluez/{hci0,hci1,...}
>
>  Methods                void RegisterMonitor(object application)
>
> -                       This registers a hierarchy of advertisement monitors.
> +                       This registers the root path of a hierarchy of
> +                       advertisement monitors.
>                         The application object path together with the D-Bus
>                         system bus connection ID define the identification of
>                         the application registering advertisement monitors.
> +                       Once a root path is registered by a client via this
> +                       method, the client can freely expose/unexpose
> +                       advertisement monitors without re-registering the root
> +                       path again. After use, the client should call
> +                       UnregisterMonitor() method to invalidate the
> +                       advertisement monitors.
>
>                         Possible errors: org.bluez.Error.InvalidArguments
>                                          org.bluez.Error.AlreadyExists
> +                                        org.bluez.Error.Failed
>
>                 void UnregisterMonitor(object application)
>
> -                       This unregisters advertisement monitors that have been
> -                       previously registered. The object path parameter must
> -                       match the same value that has been used on
> -                       registration.
> +                       This unregisters a hierarchy of advertisement monitors
> +                       that has been previously registered. The object path
> +                       parameter must match the same value that has been used
> +                       on registration. Upon unregistration, the advertisement
> +                       monitor(s) should expect to receive Release() method as
> +                       the signal that the advertisement monitor(s) has been
> +                       deactivated.
>
>                         Possible errors: org.bluez.Error.InvalidArguments
>                                          org.bluez.Error.DoesNotExist
> --
> 2.26.2

These are still experimental so you will need to use EXPERIMENTAL
version when declaring the methods/properties so it only gets enabled
when the experimental flag is passed to bluetoothd.


-- 
Luiz Augusto von Dentz