Commit 045c68cb authored by David Boddie's avatar David Boddie

Merge branch 'add-ambient-light-example' into 'master'

Add documentation for the Ambient Light example

See merge request !392
parents 3f623c96 5e9c7ab3
Pipeline #53000 canceled with stages
......@@ -31,3 +31,6 @@
[submodule "Apps/Examples/Audio/Play_Sounds/app"]
path = Apps/Examples/Audio/Play_Sounds/app
url = https://source.puri.sm/Librem5/example-apps/play-sounds.git
[submodule "Apps/Examples/Sensors/Ambient_Light/app"]
path = Apps/Examples/Sensors/Ambient_Light/app
url = https://source.puri.sm/Librem5/example-apps/ambient-light.git
.. |main-file| replace:: ``ambient-light.in``
.. |executable| replace:: ``ambient-light``
.. |desktop-entry-in| replace:: ``com.example.ambient_light.desktop.in``
.. |desktop-entry| replace:: ``com.example.ambient_light.desktop``
.. |desktop-entry-ref| replace:: desktop entry file
.. |svg-file| replace:: ``com.example.ambient_light.svg``
.. include:: /Apps/Examples/common/Building_the_App.txt
.. |project| replace:: https://source.puri.sm/Librem5/example-apps
.. |repo| replace:: ambient-light.git
.. |project-repo| replace:: ``https://source.puri.sm/Librem5/example-apps/ambient-light.git``
.. include:: /Apps/Examples/common/Getting_the_App.txt
.. |manifest| replace:: ``com.example.ambient_light.json``
.. |manifest-path| replace:: app/com.example.ambient_light.json
.. |app-id| replace:: com.example.ambient_light
.. |extra-permissions-info| replace:: We also specify the ``--system-talk-name=net.hadess.SensorProxy`` permission to request access to the `iio-sensor-proxy`_ service, using the mechanism described in the :ref:`flatpak_app_permissions_guide` guide.
.. |meson-app-module| replace:: ambient_light
.. |extra-module-info| replace:: The application's module is usually the last in the list:
.. include:: ../../common/Packaging_the_App.txt
.. include:: /links.txt
.. _Sensors_Ambient_Light_example_src:
Source Files
============
Most of the code for the application is included in a single ``main.py`` file which contains a single ``Application`` class to manage the running of the application and a ``main`` function to start it.
.. contents::
:local:
Much of the code is very similar to other examples and tutorials. We will focus on the parts that are specific to this example.
Relevant Modules
----------------
In addition to the usual modules for accessing command line arguments and GTK widgets, we use the ``Gio`` module to enable us to access D-Bus services.
.. literalinclude:: app/src/main.py
:language: python3
:start-at: import sys
:end-at: from gi.repository
The ``Gio`` and ``GLib`` modules are imported in the same way as the ``Gtk`` module.
Setting up the Application
--------------------------
The application provides an ``Application`` class with the usual methods to set up the application and perform tasks when it is run. In the ``__init__`` method we set up the application title, ID and program name to ensure that it integrates into the environment:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: class Application
:end-at: set_prgname
In the ``do_activate`` method, we create the application window and show it, but we also set up a `DBusProxy`_ object that we use to communicate with a D-Bus service providing sensor data:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: def do_activate
:end-at: None)
This proxy object emits the ``g-properties-changed`` signal when any of the properties exposed by the service change. We connect this signal to the ``properties_changed`` method in the window so that it can update the user interface with the latest sensor information:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: self.proxy.connect
:end-at: None)
The last task the ``do_activate`` does is to check for the presence of the ambient light sensor by reading the `HasAmbientLight <net.hadess.SensorProxy.HasAmbientLight_>`_ property of the D-Bus service. If this returns ``True`` we call the `ClaimLight <net.hadess.SensorProxy.ClaimLight_>`_ method of the D-Bus API to start receiving updates to the ambient light sensor.
.. literalinclude:: app/src/main.py
:language: python3
:start-at: HasAmbientLight
:end-at: None)
The ``do_shutdown`` method of the application is called just before the application exits. In this method we call the `ReleaseLight <net.hadess.SensorProxy.ReleaseLight_>`_ method of the D-Bus API to release the sensor for other applications:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: def do_shutdown
:end-at: None)
Applications should usually only claim the sensor when required and release it as soon as possible.
Creating the User Interface
---------------------------
The ``Window`` class is used to display a simple user interface that updates when new sensor data is available. We begin by creating some `Gtk.Label`_ widgets to show the information, using `Gtk.Box`_ boxes to organize them:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: class Window
:end-at: self.add
The indicator label will be used to display a simple bar graph; the level label will show the measured quantity provided by the D-Bus service.
Responding to Updates
---------------------
As described above, the ``properties_changed`` method of the ``Window`` class will be called when the properties exposed by the D-Bus service change:
.. literalinclude:: app/src/main.py
:language: python3
:start-at: def properties_changed
:end-at: (level, unit)
Since we are only interested in the ambient light level, we simply request the values of the `LightLevel <net.hadess.SensorProxy.LightLevel_>`_ and `LightLevelUnit <net.hadess.SensorProxy.LightLevelUnit_>`_ properties, updating the two labels with the new information.
Another approach to handling updated sensor information would involve examining the values passed in the ``changed`` and ``invalidated`` method parameters, and only changing the user interface if the ambient light data has changed.
Summary
-------
Handling sensor data involves requesting information from the ``net.hadess.SensorProxy`` service on the system D-Bus. Applications can create a `DBusProxy`_ object to communicate with the service. When this is done, you can subscribe to property updates by
* connecting the ``g-properties-changed`` signal to a callback method,
* checking the `HasAmbientLight <net.hadess.SensorProxy.HasAmbientLight_>`_ property for the presence of the sensor, and
* calling the service's `ClaimLight <net.hadess.SensorProxy.ClaimLight_>`_ method to start receiving updates.
When the sensor is no longer needed, call the `ReleaseLight <net.hadess.SensorProxy.ReleaseLight_>`_ method of the D-Bus API.
.. include:: /links.txt
.. _examples_Sensors_Ambient_Light_summary:
Summary
=======
Applications can access the ambient light sensor by using the `DBusProxy`_ class from the ``Gio`` module to talk to a D-Bus service. The API provided by the service can also be used to access other sensors.
When distributed as a flatpak, the manifest needs to include the ``--system-talk-name=net.hadess.SensorProxy`` permission that allows the application to access the ``net.hadess.SensorProxy`` service on the system D-Bus.
.. include:: /links.txt
Subproject commit 0937f48f66846750e9666577a3d178e58db51f1c
.. _examples_Sensors_Ambient_Light:
Ambient Light
=============
This example demonstrates a way to read values from the ambient light sensor. When run, the application shows the changing light level detected by the sensor.
.. image:: images/screenshot.png
:scale: 50%
:align: center
:alt: A screenshot of the application running in the phone environment
In :ref:`Sensors_Ambient_Light_example_src` we focus on the parts of the application that handle access to the ambient light sensor.
.. toctree::
:maxdepth: 1
Getting_the_App
Source_Code
Building_the_App
Packaging_the_App
Summary
.. include:: /links.txt
......@@ -20,6 +20,7 @@ information about the APIs used by applications.
.. toctree::
:maxdepth: 1
Sensors/Ambient_Light/index
Networking/NetworkState/index
Files/Pictures/index
Audio/Play_Sounds/index
......
......@@ -8,6 +8,7 @@
.. _`community/librem-5-apps`: https://matrix.to/#/#community-librem-apps:talk.puri.sm
.. _`community/librem-5-devkit`: https://matrix.to/#/#librem-5-devkit:talk.puri.sm
.. _`coredumpctl man page`: https://www.freedesktop.org/software/systemd/man/coredumpctl.html
.. _`DBusProxy`: https://lazka.github.io/pgi-docs/#Gio-2.0/classes/DBusProxy.html
.. _`Debian`: https://www.debian.org
.. _`Debian New Maintainers' Guide`: https://www.debian.org/doc/manuals/maint-guide/
.. _`Debian Package Builds for the Librem 5`: https://arm01.puri.sm/job/debs/
......@@ -145,6 +146,11 @@
.. _`NetworkManager`: https://wiki.gnome.org/Projects/NetworkManager
.. _`NetworkManager D-Bus APIs`: https://developer.gnome.org/NetworkManager/stable/spec.html
.. _`net.hadess.SensorProxy`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html
.. _`net.hadess.SensorProxy.ClaimLight`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html#gdbus-method-net-hadess-SensorProxy.ClaimLight
.. _`net.hadess.SensorProxy.HasAmbientLight`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html#gdbus-property-net-hadess-SensorProxy.HasAmbientLight
.. _`net.hadess.SensorProxy.LightLevel`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html#gdbus-property-net-hadess-SensorProxy.LightLevel
.. _`net.hadess.SensorProxy.LightLevelUnit`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html#gdbus-property-net-hadess-SensorProxy.LightLevelUnit
.. _`net.hadess.SensorProxy.ReleaseLight`: https://developer.gnome.org/iio-sensor-proxy/1.0/gdbus-net.hadess.SensorProxy.html#gdbus-method-net-hadess-SensorProxy.ReleaseLight
.. _`Nightly GNOME Apps`: https://wiki.gnome.org/Apps/Nightly
.. _`Ninja`: https://ninja-build.org/
.. _`Packaging Your Product`: https://www.debian.org/doc/manuals/distribute-deb/distribute-deb.html#packaging
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment