fkm-kernel-docs.md

FKM Custom Kernel Documentation

Franco Kernel Manager supports adding custom kernels to the automatic flasher. Any kernel developer can easily create a config, and users can then import the config into the app for fast and convenient kernel updates without having to manually flash anything. Update notifications are not currently supported, though support may be added in the future.

JSON Configurations

Custom kernels are defined using JSON configurations. Here is a sample configuration for a hypothetical Zen Kernel that supports the Pixel 2 series:

{
  "kernel": {
    "name": "Zen Kernel",
    "version": "v1.7.1",
    "link": "https://example.com/zen_kernel_v1.7.1-wahoo.zip",
    "changelog_url": "https://example.com/zen_kernel_v1.7.1-wahoo_changelog.txt",
    "date": "2020-01-09",
    "sha1": "c378c90f0df3d978c254f36fcc868c3ba27b43ad"
  },
  "support": {
    "link": "https://t.me/joinchat/HgJdGFUplvwv22M08rFCbw"
  }
}

Below is a list of the expected content of each key. All values are required unless otherwise specified.

• kernel: An object containing kernel-related information
  • name: Full name of the kernel, shown to the user as a header
  • version: Current kernel version, shown to the user with a "Version" label
  • link: URL to download the kernel zip to flash
    • Must be a direct link (services that require an interactive browser page, such as Google Drive and OneDrive, are not supported)
    • The app downloads the file when requested
    • Shortened links are discouraged since this is not a user-facing value
  • changelog_url: URL to download the changelog file to display
    • This must be a plain-text file; HTML and Markdown formatting are not supported
    • The app fetches and renders the changelog when requested
    • Shortened links are discouraged since this is not a user-facing value
  • date: Date the given kernel version was released on
    • Standard ISO 8601 format (YYYY-MM-DD) is encouraged to facilitate the display of a localized date to users
    • Raw strings are also supported for alternative formats, but this is discouraged
  • sha1: Expected checksum of the downloaded kernel zip
    • This is a SHA-1 checksum
    • Readily generated using the sha1sum command on Unix-like systems
• support: An object containing support-related information (optional)
  • link: URL to visit for users to obtain support for the kernel (optional)
    • For example, this can be a link to a Telegram support chat or XDA-Developers thread
    • Custom protocols are supported since Android handles this
    • Shortened links are discouraged since this is not a user-facing value

Similar to the kernel zip, the JSON file must also be hosted on a service that supports direct downloads. GitHub is one such service; you can push the JSON to a separate repository, branch, or release on GitHub and create a raw download URL — there are plenty of online guides covering this. You can also choose to host the JSON on your own server. Users simply paste the JSON URL into a dialog in the app to add a kernel. Shortened links can be used to make this process easier.

Direct URLs

As mentioned above, all URLs (with the exception of the support link) must be direct. This means that they may not include browser interactive pages at all. Redirects, however, are permitted as long as they are also direct (i.e. using HTTP redirects rather than browser ones defined in HTML).

A general method of verifying this is to visit the given link in a new browser tab. If the page stays white the entire time, never loads any content, and starts a file download, it is direct. On the other hand, if any content appears on the screen, it is considered indirect. Likewise, a visible delay or countdown page is also indirect.

Device Customization

It is possible to serve different configurations based on the Android version and/or device in use. This is enabled by FKM's user agent, which follows the standard scheme in the User-Agent HTTP header. For example, a Pixel 2 XL running Android 10 would send a user agent similar to FKM/4.10 Android/10 (taimen). This information can be used to customize the response sent to the client, or reject the request if the device is unsupported.

Note that it is not possible to do this on GitHub and most other public file hosting services as they do not allow running server-side code. However, web hosting services should allow this. You must create your own simple server logic to handle this as there is no reference implementation available at this time.

---

Written with ❤️ by @kdrag0n