Skip to content

Detailed subsystem adaptation guides#

Sailfish OS uses some kernel interfaces directly, bypassing the android HAL. Mainly this is used in places where the kernel API is stable enough and also used by Android. The other reasons for using kernel APIs directly include better features offered by standard kernel frameworks, differing middleware between Sailfish OS linux and Android, and lastly special features of Sailfish OS.

Vibration / force feedback#

The default vibra framework that is used in full featured productized Sailfish OS devices is the force feedback API in kernel input framework. The kernel drivers should either use the ffmemless framework OR provide FF_PERIODIC and FF_RUMBLE support via as a normal input driver. In this chapter we go through the ff-memless aproach of adapting your kernel for Sailfish OS

This is a different method than what is used in community Sailfish OS ports, which utilize the android vibrator / timed-output API. The android vibrator plugins in Sailfish OS middleware have very reduced feature set, and are not recommended for commercial products.

In order to utilize the standard input framework force feedback features of Sailfish OS, the android timed output vibrator kernel driver needs to be converted to a ffmemless driver. The main tasks for this are:

diff --git a/drivers/input/ff-memless.c b/drivers/input/ff-memless.c
index 117a59a..fa53611 100644
--- a/drivers/input/ff-memless.c
+++ b/drivers/input/ff-memless.c
@@ -39,7 +39,7 @@ MODULE_AUTHOR("Anssi Hannula <anssi.hannula@gmail.com>");
 MODULE_DESCRIPTION("Force feedback support for memoryless devices");

 /* Number of effects handled with memoryless devices */
-#define FF_MEMLESS_EFFECTS     16
+#define FF_MEMLESS_EFFECTS     64

 /* Envelope update interval in ms */
 #define FF_ENVELOPE_INTERVAL   50
  • Optionally you can decrease ff-memless control interval so that fade and attack envelopes can be used in short haptic effects as well:
diff --git a/drivers/input/ff-memless.c b/drivers/input/ff-memless.c
index 89d3a3d..33eee2e 100644
--- a/drivers/input/ff-memless.c
+++ b/drivers/input/ff-memless.c
@@ -41,7 +41,7 @@ MODULE_DESCRIPTION("Force feedback support for memoryless devi
 #define FF_MEMLESS_EFFECTS     64

 /* Envelope update interval in ms */
-static int ff_envelope_interval = 50;
+static int ff_envelope_interval = 10;
 module_param(ff_envelope_interval, int, S_IWUSR | S_IRUGO);

 #define FF_EFFECT_STARTED      0

The userspace configuration haptic feedback and effects is handled with ngfd configuration files, see more details in Middleware / NGFD

GStreamer v1.0#

Sailfish OS 2.0 introduces GStreamer v1.0 with hardware-accelerated video and audio encoding and decoding in Camera, Gallery and Browser, and deprecates GStreamer v0.10.

The GStreamer-droid bridge is part of the integral build process. If you need to modify its source code, then rebuild it via:

PLATFORM SDK
cd $ANDROID_ROOT
rpm/dhd/helpers/build_packages.sh --gg

Camera#

Launch the Camera app. If if shows black screen and becomes non-responsive, enable the audiosystem-passthrough-dummy-af package in the patterns and rebuild droid-configs.

If you find some parameters (such as ISO speed or other 3A settings) are missing from camera app, then it's possible that your camera device is designed to use an older version of the Camera HAL than the default. You can try forcing a HAL v1 connection by adding FORCE_HAL:=1 to env.mk in droidmedia.

Cellular modem#

  • Ensure Android's RIL running ps ax | grep rild (expect one or two /system/bin/rild)

  • If RIL is not running, check why it is not launched from /init*.rc scripts

  • If it's launched, check where it fails with /usr/libexec/droid-hybris/system/bin/logcat -b radio

  • Errors in RIL might look like this: 

    RIL[0][main] qcril_qmi_modem_power_process_bootup: ESOC node is not available
    After online search this suggests firmware loading issues on Motorola Moto G. Compare with a healthy radio logcat after booting back into CM, not all lines starting with E/RIL... will point to a root cause!

  • If it's firmware loading problem, trace all needed daemons in CM and their loading order as well as all mounted firmware, modem, and baseband partitions.

  • Once RIL is happy, then ofono can be launched. Unmask it if it was previously masked due to causing reboots in bootloops.

  • If you still get no signal indicator in UI, remove SIM PIN and retry

  • Also install ofono-tests package and run /usr/lib/ofono/test/list-modems

  • Try to recompile latest ofono master branch from https://github.com/sailfishos/ofono

  • If everything else fails, then stop and strace a failing daemon (either RIL or ofono) from command line manually

Phone calls don't work (but SMS and mobile data works)#

If the calling parties cannot hear one another, then the audiosystem-passthrough-dummy-af middleware package is required, which should be enabled in the patterns.

Bluetooth#

For bluetooth Sailfish OS uses BlueZ stack from linux.

Todo

  • bluetooth adaptation guide.
  • add detail about audio routing.

WLAN#

Typically WLAN drivers are external kernel modules in android adaptations. To set up WLAN for such devices, a systemd service file needs to be created that loads the kernel module at boot. In addition to this you need to check that firmware files and possible HW tuning files are installed in correct locations on the filesystem.

Sailfish OS WLAN adaptation assumes the driver is compatible with WPA supplicant. This means the WLAN device driver has to support cfg80211 interface. In some cases connman (the higher level connection manager in Sailfish) accesses directly the WLAN driver bypassing wpa_supplicant.

The version of currently used wpa_supplicant can be checked from here:

The version of used connman can be checked from here:

Special quirks: WLAN hotspot#

On some android WLAN drivers, the whole connectivity stack needs to be reset after WLAN hotspot use. For that purpose there is reset service in dsme, please see details how to set that up for your adaptation project in here:

NFC#

Currently there is no NFC middleware in Sailfish OS. Android HAL API support should be enough for future compatibility.

GPS#

Ensure the test_gps command gets a fix after a while.

The necessary middleware is already built for you, just add geoclue-provider-hybris package into your patterns.

Audio#

For audio, Sailfish OS uses PulseAudio as the main mixer. For audio routing ohmd is used.

Todo

Add info about audio routing configuration TODO: Add more info in general.

Sensors#

Sailfish OS sensor support is based upon Sensor Framework at: https://github.com/sailfishos/sensorfw

Hybris based systems can use the hybris sensor adaptor plugins, which uses existing android libhardware sensor adaptations to read sensor data and control.

It can also be configured for standard linux sysfs and evdev sensor interfaces.

It should be configured at /etc/sensorfw/primaryuse.conf, which links to a device specific conf file. Historically named sensord-<BOARDNAME>.conf. You can also use any conf file by specifying it on the commandline.

For hybris based platforms, this will be sensord-hybris.conf, and most likely will not have to be modified. A copy of this file is already among default configs: https://github.com/sailfishos/sensorfw/blob/master/config/sensord-hybris.conf If you do make modifications to it, add the file under $ANDROID_ROOT/hybris/droid-configs/sparse/etc/sensorfw/primaryuse.conf

There are already a few device specific conf files to look at if the device needs more configuration. Example of mixed hybris and evdev configuration https://github.com/sailfishos/sensorfw/blob/master/config/sensord-tbj.conf

Generally, if sensors are working on the android/hybris side, they will work in sensorfw and up to the Sailfish UI. libhybris comes with /usr/bin/test_sensors which can list those Android sensors found.

Above Sensor Framework is QtSensors, which requires a configuration file at /etc/xdg/QtProject/Sensors.conf which is supplied with the sensorfw backend plugin in QtSensors and a copy of it is already among your default configs.

For Sailfish Core based systems, the QtSensors source code is at: https://github.com/mer-qt/qtsensors

Debugging output of sensorfwd can be increased one level during runtime by sending (as root) USR1 signal like so: pkill -USR1 sensorfwd or specified on the commandline for startup debugging.

Sending pkill -USR2 sensorfwd will output a current status report.

Power management#

Under the hood, Sailfish OS uses the android wake locks. Typically there is no need to change anything in the kernel side (assuming it works fine with android) for the power management to work, as long as all the device drivers are working normally.

The userspace API's for platform applications is exposed via nemo-keepalive package. See more details here:

Watchdog#

A standard linux kernel watchdog core driver support is expected. The device node should be in /dev/watchdog. It should be configured with following kernel options:

CONFIG_WATCHDOG=y
CONFIG_WATCHDOG_CORE=y
CONFIG_WATCHDOG_NOWAYOUT=y

Note

Please note that watchdog driver should disable itself during suspend.

Note

Normally the watchdog period is programmed automatically, but if your driver does not support programming the period, the default kicking period is 20 seconds.

Touch#

Sailfish OS is compatible with standard kernel multitouch input framework drivers. Protocol A is preferred. The main configuration needed is to symlink the correct event device node to /dev/touchscreen. To do this the best way is to set up a udev rule that checks the devices with evcap script and creates the link once first valid one is found. See more details for evcap here:

The udev rule can be put to file /lib/udev/rules.d/61-touchscreen.rules

The reason this is not done by default is that typically driver authors mark bit varying capabilities as supported and there could be multiple touch controllers on a device, so the final rule is best to be written in a device specific configs package.

Note

if you still have problems with touch, please check that lipstick environment has correct touch device parameter: 

cat /var/lib/environment/compositor/droid-hal-device.conf
LIPSTICK_OPTIONS should have "-plugin evdevtouch:/dev/touchscreen"

Special feature: double tap to wake up#

Sailfish OS supports waking up the device from suspend (unblanking the screen) via double tap gesture to the touchscreen. The touchscreen driver should either emulate KEY_POWER press / release or post a EV_MSC/MSC_GESTURE event with value 0x4 when double tap gesture is detected when waking up from suspend.

In order to avoid excess power drain when device is in pocket facing users skin, some sysfs should be exported to allow disabling the touch screen. The feature requires that the device has a working proximity sensor that can wake up the system when it is suspended (to be able to update touch screen state according to need). To configure MCE that handles this see MCE configuration