droid-configs-device
====================

``droid-configs-device`` contains instructions on how to configure the
Sailfish OS. It defines extra packages that should get installed, contains
config files in ``sparse/{etc,usr,var,...}`` tells the Sailfish OS whether the
device has certain features like blueooth and configures parts of the mer
stack like ``ofono``.

<!-- TODO: Add tooltip box here -->
**Commonly abbreviated as `d-h-c`.**

The mer-hybris repo is - confusingly - named `droid-hal-configs`_ but gets
cloned as ``droid-configs-device``.

Set-up Instructions
^^^^^^^^^^^^^^^^^^^

Clone ``droid-config-$DEVICE`` into ``hybris/droid-configs``. Then sync the
submodule by going into ``hybris/droid-configs`` and running
``git submodule init`` and then ``git submodule update``. This will create
``hybris/droid-configs/droid-configs-device``.

Structure
^^^^^^^^^

``droid-configs-device`` follows the ``[[INTERLINK|Submodule Structure]]`` of having
one specific ``hybris/droid-X-$DEVICE`` repo with the generic packaging repo inside
``droid-X-$DEVICE/droid-X``.

Tree for ``hybris/droid-configs`` (abridged):

.. code::

   droid-configs
   ├── droid-configs-device
   │   ├── droid-configs.inc
   │   ├── helpers
   │   │   └── process_patterns.sh
   │   ├── patterns
   │   │   └── templates
   │   │       ├── jolla-configuration-@DEVICE@.yaml
   │   │       └── jolla-hw-adaptation-@DEVICE@.yaml
   │   └── sparse
   │       └── etc
   │           └── acdbdata -> /system/etc/acdbdata
   ├── patterns
   │   ├── jolla-configuration-$DEVICE.yaml
   │   └── jolla-hw-adaptation-$DEVICE.yaml
   ├── rpm
   │   └── droid-config-$DEVICE.inc
   └── sparse
       └── boot
           └── flash.sh

droid-config-$DEVICE.spec
^^^^^^^^^^^^^^^^^^^^^^^^^

+-----------------------+------------------------------------------------------+
| Macro                 | Explanation                                          |
+=======================+======================================================+
| device                | Should be the LineageOS codename or the ``AOSP``     |
|                       | ``TARGET_PRODUCT`` (e.g. ``kagura``) and correspond  |
|                       | to the droid-side ``./device/%{vendor}/%{device}``   |
|                       | folder structure                                     |
+-----------------------+------------------------------------------------------+
| vendor                | Determines the droid-side directory used for         |
|                       | ``./device/%{vendor}/%{device}``, e.g. ``sony``      |
+-----------------------+------------------------------------------------------+
| device_pretty         | User-visible model name of the device                |
+-----------------------+------------------------------------------------------+
| vendor_pretty         | User-visible manufacturer name of the device         |
+-----------------------+------------------------------------------------------+
| rpm_device            | Device name used rpm-side(eg in configs); defaults   |
|                       | to ``%{device}``.                                    |
+-----------------------+------------------------------------------------------+
| rpm_vendor            | Vendor name used rpm-side(e.g. in configs), should   |
|                       | be the device SoC vendor, e.g. ``qualcomm``          |
+-----------------------+------------------------------------------------------+
| ofono_enable_plugins  | Any additional ofono plugins that you want           |
|                       | explicitly enabled                                   |
+-----------------------+------------------------------------------------------+
| ofono_disable_plugins | Any ofono plugins that you want explicitly disabled  |
+-----------------------+------------------------------------------------------+
| remove_modem          | Set this if your device has no modem (e.g. a         |
|                       | WiFi-only tablet)                                    |
+-----------------------+------------------------------------------------------+
| remove_bluetooth      | Set this if your device does not have a Bluetooth    |
|                       | chip                                                 |
+-----------------------+------------------------------------------------------+
| pixel_ratio           | UI scaling factor, choose from 1.0, 1.5, 2.0. Any    |
|                       | other value will default the icon pack to 1.0        |
|                       | resolution (it is a bug)!                            |
+-----------------------+------------------------------------------------------+

**Warning:** ``pixel_ratio`` is experimental, and not yet ready for proper UI
scalability tests! Please do not test/port your apps to other form factors for
the time being.

Ratio examples:

============= ===========
Device        Pixel Ratio
============= ===========
Jolla1        1.0
Jolla Tablet  1.5
Nexus 5       2.0
Nexus 4       pixel_ratio=1.3 (icon resolution then drops to 1.0)
============= ===========

.. _droid-hal-configs: https://github.com/mer-hybris/droid-hal-configs