Commit 5e9c7ab3 authored by David Boddie's avatar David Boddie

Add documentation for the Ambient Light example

parent acd53733
......@@ -31,3 +31,6 @@
[submodule "Apps/Examples/Audio/Play_Sounds/app"]
path = Apps/Examples/Audio/Play_Sounds/app
url =
[submodule "Apps/Examples/Sensors/Ambient_Light/app"]
path = Apps/Examples/Sensors/Ambient_Light/app
url =
.. |main-file| replace:: ````
.. |executable| replace:: ``ambient-light``
.. |desktop-entry-in| replace:: ````
.. |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::
.. |repo| replace:: ambient-light.git
.. |project-repo| replace:: ````
.. 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 ```` file which contains a single ``Application`` class to manage the running of the application and a ``main`` function to start it.
.. contents::
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/
: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/
: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/
: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/
: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/
: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/
: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/
: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/
: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.
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:
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
.. include:: /links.txt
......@@ -20,6 +20,7 @@ information about the APIs used by applications.
.. toctree::
:maxdepth: 1
......@@ -8,6 +8,7 @@
.. _`community/librem-5-apps`:
.. _`community/librem-5-devkit`:
.. _`coredumpctl man page`:
.. _`DBusProxy`:
.. _`Debian`:
.. _`Debian New Maintainers' Guide`:
.. _`Debian Package Builds for the Librem 5`:
......@@ -145,6 +146,11 @@
.. _`NetworkManager`:
.. _`NetworkManager D-Bus APIs`:
.. _`net.hadess.SensorProxy`:
.. _`net.hadess.SensorProxy.ClaimLight`:
.. _`net.hadess.SensorProxy.HasAmbientLight`:
.. _`net.hadess.SensorProxy.LightLevel`:
.. _`net.hadess.SensorProxy.LightLevelUnit`:
.. _`net.hadess.SensorProxy.ReleaseLight`:
.. _`Nightly GNOME Apps`:
.. _`Ninja`:
.. _`Packaging Your Product`:
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment