Supporting the PinePhone's hardware and also supporting hardware for other devices.

[DrewNaylor]

(This will be edited to be more concise; just copying over things for now.)

(note Oct. 3, 2023: I'm relicensing to the GPL, so I'll just use the idea with the Generic Driver thing I have to support multiple devices)

Discussed in https://github.com/DrewNaylor/Retiled/discussions/16

^{Originally posted by **DrewNaylor** June 3, 2021} I really don't want to do this because I don't like the GPL as it's so restrictive and is involved with the same organization as RMS, but there's this .NET 5 library for getting PinePhone hardware stuff that would be really useful and it's GPLv2 licensed: https://github.com/Alumniminium/PinePhoneCore As a result of changing this to the GPLv2 (would prefer v3+ as it allows Apache Licensed stuff, but the license isn't v2+ as far as I can tell), I'd have to change some of my other projects I'm planning on using to use the Expat License (some call it the "MIT License", but that's inaccurate). Just trying to see if there's any feedback about this.

[DrewNaylor]

Comment posted on the above-linked discussion

^{Originally posted by **DrewNaylor** July 6, 2021} Actually, I may be able to keep the main part of the project under the Apache License 2.0 and just make a GPL'd CLI application that uses the PinePhone hardware library to send information back to the Standard Out. The benefit of this is that the GPL won't infect the main code for Retiled, and the CLI program can be easily replaced with something that's not under the GPL as long as the input and output stuff is compatible. It may even be possible to use something like Python instead just to be able to avoid using a GPL'd library in the first place.

[DrewNaylor]

Comment posted on the above-linked discussion

^{Originally posted by **DrewNaylor** August 12, 2021} Perhaps it would be a good idea to build an MEF plugin that uses the GPL'd PinePhoneCore library to make porting to other phones easier and allow people to delete or replace the plugin if they don't want GPL'd code to be used. I hope that's acceptable to the GPL, considering the plugin would be completely optional and easy to replace.

[DrewNaylor]

Comment posted on the above-linked discussion

^{Originally posted by **DrewNaylor** August 12, 2021} Actually, what I will probably do is build both a "Basic Hardware Support for PinePhone" plugin and an "Enhanced Hardware Support for PinePhone" plugin. The enhanced one will have to be downloaded and installed separately from Retiled because the plugin will call directly into PinePhoneCore's code, but the basic one can be included in the package because it'll be calling a CLI app that returns requested info via stdout. As a result, the basic plugin's main DLL can be under the Apache License 2.0, with its corresponding CLI app under the GPLv2. I'm pretty sure this is ok because the CLI app and PinePhoneCore run as their own process, separate from Retiled's processes that'll use it. I'm not distributing the enhanced plugin with Retiled, so the user will have to download and install it themselves, but there will be an install script (and uninstall script) to make it easy.
The benefit of the enhanced plugin over the basic one is that it doesn't have to run a separate program just to get info or do stuff like vibrate when pressing the navigation buttons. This may make things faster and reduce battery usage because it won't be constantly starting .NET to get the battery percentage, for example. One potential drawback of the basic plugin is that it won't be able to do things that require being used via events, as it wouldn't be aware of anything that happens beyond what the CLI app says when it runs it. Maybe pipes could alleviate some of that, but I don't think it would be allowed.
There would have to be a way to configure which hardware support plugin the user wants to use, so that the enhanced and basic plugins can be installed and uninstalled without affecting each other. This will be very important whenever hardware support plugins for other devices like the Librem 5 are developed, so the user can install the plugin they need without having to uninstall the basic PinePhone one first.

[DrewNaylor]

Actually, perhaps I could develop my own library by using various documentation from Megi, since there's a lot of good stuff there. I can also use ofonocli from Martijn Braam to get modem info for apps in UIs that use it as well as mmcli for ModemManager (this'll eventually be the default for Plasma Mobile, so I should probably focus on it). Here's a page on ofonocli commands: https://sr.ht/~martijnbraam/ofonoctl/ mmcli commands: https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/debugging-3g/modem-debugging-with-mmcli

A bit more research on this shows that mmcli -m 0 -K will give values in key-value pairs, which will make displaying signal strength and whether the sim card is in or not easy as long as I clean up the output for processing. The "-K" argument was in a comment on the accepted answer to this question: https://unix.stackexchange.com/questions/586528/gsm-modem-get-signal-strength

Decided to run ofonoctl on its own, and it shows the available modems along with their status.

[DrewNaylor]

Even if I do write my own library (which I will, since I can fine-tune it to what I need while avoiding licensing issues), I'll still have to ensure people can install libraries to support other devices. Perhaps a "dummy library" that acts as a bridge interface would work, so that other libraries can just be connected to and provide data back and forth using that bridge. (Not sure how that would be implemented to switch libraries at runtime, though). If I don't do that, then more work will have to be done, resulting in duplicated code. I may have to have general hardware sensors and stuff separate from code that interacts with mmcli, since that would probably be more common across Linux phones than would general hardware stuff. Hopefully most phones can just be supported with different config files rather than a customized hardware support library, as that would be way easier.

[DrewNaylor]

As I mentioned above regarding plugins, I'm going to have to have an easy way to support multiple devices. I thought of a name for the ones that only involve running different commands such as when toggling the flashlight: Generic Driver Configuration Architecture, or GDCA (it could also be named "Generic Driver Engine for Retiled (Configuration Architecture)", or "GDER(CA)", with the "CA" possibly being added when describing the file format for the "Generic Driver Engine for Retiled", which would be the software and libraries themselves that read the configuration files). I probably described the idea for these somewhere, but they're just INI config files that specify what command should be run when something wants to for example do flashlight_on. But still, some devices won't just be fine with commands, so we may need to expand the capabilities of these config files to take into account watching the device's rotation and volume and stuff if that can't be done using configs (but it should be able to, even if like the rotation has to be read from sysfs instead of running a command; actually, maybe that could work, have a D-Bus server watching for updated from the rotation then sending it out when it hits a specific angle, but we have to also have a way to make it pause reading the value if rotation lock is off)

Not sure if I described this anywhere yet, but I think the file tree can be for example, (repo root)/drivers/pinephone/hardware_v1.2-beta.ini. A better layout probably exists. There also needs to be a way for specific operating systems to have their own config file, maybe with hardware_v1.2-beta_manjaro-plasmamobile.ini for an example file. First we'll look for the most specific file (one containing the environment, OS, and hardware revision), then the hardware revision, then just hardware.ini. Maybe there can also be a way to have files for specific components, if only a few things change between hardware revisions or operating systems. This can be (for example) flashlight.ini, along with the hardware revision and operating system strings and stuff.

As likely mentioned before, we need to also offer a way for the user to pick their configuration file directly in case we decide incorrectly, such as on a modified device that hasn't called themselves something different from something we support yet, or if a device is close enough to something else to mostly work, like with OnePlus and the other company I forgot (but I don't know how similar the devices are from those two companies, so changes may be necessary).

[DrewNaylor]

Adding to this, rotation axis can be determined via sysfs iio, and what the PinePhone uses is described on the page for it on the postmarketOS Wiki under Components, Sensors: https://wiki.postmarketos.org/wiki/PINE64_PinePhone_(pine64-pinephone)

Not sure if it's possible or even a good idea to constantly read it, so maybe polling every 60-300 ms will be necessary. This number is subject to change, and it would be a good idea to allow it to be customized by the user in an advanced settings page somewhere. Rotation Lock will turn off polling for rotation, and apps need to have a way to say that they don't want to rotate, or that they want to stay in a specific orientation. Not sure how to handle apps that want to get rotation info with Rotation Lock off.

Edit: This page has degree values for when a rotation occurs, that being at 60 degrees when going from portrait to landscape left or right or back to portrait (depending on the tilt direction), and 30 degrees up when flat on a table in landscape left or right going to portrait. Also, the status bar goes from 32 pixels in portrait to 72 in landscape. Finally, physical horizontal keyboards would rotate the display horizontally for that keyboard, so there needs to be support to automatically do that, for example with the F(x)tec Pro1 and the Astro Slide; the PinePhone Keyboard Case is always open when using the phone's touch screen, so that wouldn't work. Source and screenshots for archival: https://learn.microsoft.com/en-us/previous-versions/windows/apps/hh202911(v=vs.105)

[DrewNaylor]

Qt has window orientation flags apparently, where they're defined here (this is my copy of the repo) : https://github.com/drewnaylor/qtwayland/blob/dev/src/extensions/surface-extension.xml

Learned about that file from this issue: https://github.com/libsdl-org/SDL/issues/1826

Obviously, InvertedLandscapeOrientation is what we'll use for rotating the other way, and also for the compositor to move system UI stuff like the status and navigation bars as necessary. Might look a bit janky at first, but if it works, it's fine until it's polished.

Also in that file are window flags, such as OverridesSystemGestures, StaysOnTop, and BypassWindowManager. Not sure how BypassWindowManager could be used, but OverridesSystemGestures sounds like could be used to turn off the "swipe to hide navigation bar" feature (then it would just always be on screen, so the user can easily access it), and it would also make the Action Center just have the small bar so it has to be pulled down twice to open.