Merge pull request #507 from amartinz/porting/deviceinfo

porting: configuration: add initial instructions for DeviceInfo

porting/configure_test_fix/Display.rst

@@ -19,6 +19,9 @@ The method for deriving values for these variables :ref:`is explained below. <Di
 
 Once you have adjusted the ``android.conf`` file to the display settings needed for your device, this file should be incorporated into your build. Follow :ref:`the overlay file method <Overlay-steps>` corresponding to your Halium version. 
 
+.. note::
+    This way of configuration is considered legacy, please migrate to :ref:`DeviceInfo <DeviceInfo>`.
+
 .. _Display-settings:
 
 Determining the correct display settings

porting/configure_test_fix/device_info/Repowerd.rst

@@ -0,0 +1,31 @@
+.. _DeviceInfo_Repowerd:
+
+Repowerd
+========
+
+Overview of all repowerd keys::
+
+    <devicename>:
+      BacklightSysfsPath: </path/to/the/device>
+
+Device quirks
+-------------
+
+==================  =============================  =========
+Key                 Description                    Value(s)
+==================  =============================  =========
+BacklightSysfsPath  File path to backlight device  File path
+==================  =============================  =========
+
+Examples
+--------
+
+Device `sample` using with:
+
+- Custom backlight sysfs path to disable autodetection of the path controlling the backlight
+
+Config file::
+
+    $ cat /etc/deviceinfo/devices/sample.yaml
+    sample:
+      BacklightSysfsPath: /sys/class/backlight/panel0-backlight

porting/configure_test_fix/device_info/index.rst

@@ -0,0 +1,55 @@
+.. _DeviceInfo:
+
+DeviceInfo
+==========
+
+DeviceInfo allows to set device specific configuration, which can be accessed in an uniform way using `libdeviceinfo <https://gitlab.com/ubports/development/core/deviceinfo>`_.
+
+Configuration files per device are located at ``/etc/deviceinfo/devices/[device].yaml``.
+It will try to autodetect the correct configuration to load based on model of the device,
+using android props for halium/android devices and dtb for native linux devices.
+
+.. note::
+    This file needs to be all lowercase, as any autodetected device name will be converted to lowercase.
+
+For example, the file for the Nexus 7 tablet (flo) would be located at ``/etc/deviceinfo/devices/flo.yaml`` and needs to start with the device's name::
+
+    $ cat /etc/deviceinfo/devices/flo.yaml
+    flo:
+      DeviceType: tablet
+      GridUnit: 18
+      WebkitDpr: 2
+      PrimaryOrientation: Landscape
+      ...
+
+If no device specific configuration exists or a key is not specified for the device config, DeviceInfo will fallback to ``/etc/deviceinfo/default.yaml``.
+Keep your configuration simple and try to not duplicate any entries, which are already defined in ``default.yaml``.
+
+Any key can be added without needing to modify deviceinfo to use it.
+This allows for a lot of flexibility, however keys should be properly documented in order to not duplicate keys.
+
+Built-in config keys
+--------------------
+
+============================  =========================================================  =====================================================
+Key                           Description                                                Value(s)
+============================  =========================================================  =====================================================
+Name                          Device name / codename                                     Any string
+PrettyName                    Pretty name of the device                                  Any string
+DeviceType                    Sets device type                                           desktop, tablet, phone
+GridUnit                      Sets scale units                                           Any integer
+SupportedOrientations         Orientations supported by the device                       Portrait, InvertedPortrait, Landscape, InvertedLandscape
+PrimaryOrientation            Primary orientation of the device                          Portrait, InvertedPortrait, Landscape, InvertedLandscape
+PortraitOrientation           Orientation of the device when in portrait mode            Portrait, InvertedPortrait, Landscape, InvertedLandscape
+InvertedPortraitOrientation   Orientation of the device when in inverted portrait mode   Portrait, InvertedPortrait, Landscape, InvertedLandscape
+LandscapeOrientation          Orientation of the device when in landscape mode           Portrait, InvertedPortrait, Landscape, InvertedLandscape
+InvertedLandscapeOrientation  Orientation of the device when in inverted landscape mode  Portrait, InvertedPortrait, Landscape, InvertedLandscape
+============================  =========================================================  =====================================================
+
+Other keys are documented in the component specific subpages.
+
+.. toctree::
+   :maxdepth: 1
+   :name: device_info
+
+   Repowerd

porting/configure_test_fix/index.rst

@@ -15,6 +15,7 @@ As you go along, it can be helpful to have a list of device functions to go by w
    :maxdepth: 1
    :name: configure_test_fix
 
+   device_info/index.rst
    Lomiri
    Overlay
    Display