View Source ReflectOS Kernel

Test Hex.pm Version

About

ReflectOS is the approachable, configurable, and extensible OS for your smart mirror project. It is designed to allow anyone to easily install, customize, and enjoy a smart mirror/display - no coding or command line usage required! Instructions for installing on your device and more details about ReflectOS can be found on the ReflectOS Firmware project.

This package provides the foundation for developers in the community to extend the OS by building their own sections, layouts, and layout managers.

Warning!

This project is being actively developed, and the API is not currently stable. That said, would love feedback from those using it to build their own ReflectOS extensions on how it can be improved and further stabilized. Please feel free to open an issue on the library GitHub with an suggestions.

Extending ReflectOS

Getting Started

ReflectOS allows developers to extend it's functionality by creating elixir libraries which register the extension with the system. New sections, layouts, and layout managers can all be added to the OS via extension libraries (which are just standard elixir packages containing new ReflectOS modules).

The best way to start building your own extension library is to create a standard new elixir project using the mix new command, for example:

$ mix new reflect_os_myextensions --sup

Note that it is a good idea to use the --sup option to generate the application calback, this is a great place to register the modules you build with the ReflectOS system (more on that later).

Then, bring this package to your project by adding reflect_os_kernel to your list of dependencies in mix.exs:

def deps do
  [
    {:reflect_os_kernel, "~> 0.10.0"}
  ]
end

Creating an Extension

Creating an extension is essentially just creating a module in your library which implements the proper elixir behavior. Most extensions are comprised of a set of callbacks which describe both the runtime behavior and configuration experience through the ReflectOS Console.

See the documentation for ReflectOS.Kernel.Section, ReflectOS.Kernel.Layout, and ReflectOS.Kernel.LayoutManager for more details on how to get started.

Note that while Layout Managers are built on top of GenServer, Sections and Layouts are built on top of Scenic.Scene from the Scenic UI Framework. If you are building your own Section or Layout, it is highly recommended you familiarize yourself with Scenic before getting started.

Registering

Once created, extensions modules must be registered with ReflectOS in order to be available in the console web application which allows users to manage their displays. Best practice is to do so via a supervised task during your application start up (this is why we recommend creating new projects with the --sup option).

For example:

defmodule MyReflectOSExtensions.Application do
  @moduledoc false

  use Application

  alias ReflectOS.Kernel.Section.Registry, as: SectionRegistry
  alias ReflectOS.Kernel.Layout.Registry, as: LayoutRegistry
  alias ReflectOS.Kernel.LayoutManager.Registry, as: LayoutManagerRegistry

  @impl true
  def start(_type, _args) do
    children = [
      # Start a task to register ReflectOS extensions
      {Task, fn -> reflect_os_register() end}
    ]

    opts = [strategy: :one_for_one, name: MyReflectOSExtensions.Supervisor]
    Supervisor.start_link(children, opts)
  end

  defp reflect_os_register() do
    # Sections
    SectionRegistry.register([
      MyReflectOSExtensions.Sections.MyNewSection,
    ])

    # Layouts
    LayoutRegistry.register([
      MyReflectOSExtensions.Layouts.MyNewLayout
    ])

    # Layout Managers
    LayoutManagerRegistry.register([
      MyReflectOSExtensions.Layouts.MyNewLayoutManager
    ])
  end
end

Adding Extension Libraries to ReflectOS

To test your library and create a custom ReflectOS firmware image which includes your extensions, clone the latest release of the ReflectOS Firmware. Be sure to checkout a release (e.g. use the -b flag), as the main branch may not be stable. For example:

$ git clone https://github.com/reflect-os/firmware.git my_custom_firmware -b v0.9.0

Be sure to use the version number of the most recent release!

From there, it's as simple as adding your library as a dependency to the firmware's mix.exs file! We recommend starting using the path option to refer to a local directory during development (see Mix.Tasks.Deps for more information on the various way to reference a dependency).

Once you've added your extension library as a dependency, follow the getting started instructions in the Firmware's Readme to see your project in action!

Examples

For examples of how to build your own extensions to ReflectOS, check out the ReflectOS Core project. These are extensions which are shipped with the pre-built ReflectOS firmware.

Contributing

Contributions are welcome for this project! You can open an issue to report a bug or request a feature enhancement. Code contributions are also welcomed, and can be submitted by forking this repository and creating a pull request.

Learn More

Full documentation can found on HexDocs.