Fledex

Fledex is a small Elixir library It really is intended for educational purposes. It is written for a RaspberryPi Zero W running Nerves especially with a Nerves-Livebook, but you could use it without Nerves or Livebook.

The intent of the library is to simplify the programming of a programmable LED strip (currently based on a WS2801 chip) and thereby to make it accessible even for kids.

The idea is to introduce similarly easy concepts for the programming of LEDs as SonicPi did for music. The library was developed in collaboration with my son and hopefully we can push it to become better over time. For my son the goal will be to connect the LEDs to some music and to animate the LEDs depending on the beat.

Quite a lot of inspiration came from the FastLED project and quite a few of their functions got reimplemented in Elixir. If you look at the implementation of some of those functions you might want to look at their comments.

Installation

The library is available in Hex, the package can be installed by adding :fledex to your list of dependencies in mix.exs:

def deps do
  [
    {:fledex, "~> 0.5"}
  ]
end

Usage

The smoothest way is to use the Fledex DSL which defines some functions and macros. To enable them you need to use Fledex. This will (by default) start the animation manager (Fledex.Animation.Manager) through which all led definitions are routed. But don't worry, you won't really see it.

Note: by enabling the DSL through the use Fledex call, the most important modules are aliased: Fledex.Leds, Fledex.LedStrip, Fledex.Utils.PubSub, Fledex.Color.Names, and the different drivers (all part of the FledexDriver.Impl namespace). We will see a bit later what functionality those modules provide.

As a next step you define an LED strip through the led_strip macro. While defining the led strip you need to decide on how you want to talk to your strip; you need an appropriate driver. There are several ways on how you can address your LED strip. The most common ways are through an SPI bus (Fledex.Driver.Impl.Spi) or through Kino (Fledex.Driver.Impl.Kino) as a simulated LED strip in Livebook. It is possible to adjust the settings of the drivers, or even define several drivers at the same time.

This will look like the following:

led_strip Spi do
  # ... here comes the definition of your leds ...
end

Once we have defined our led strip we can start to define sequences of leds. This can be achieved in 4 different ways:

• static: a static set of leds that do not change over time
• animation: an animated, i.e. changing set of leds
• component can encapsulate (and make the usage) of already predefined static and animated set of leds easier.

All of them define a function that defines a sequence of leds (Fledex.Leds). which might (or might not) change over time to give the desired effects.

Combined this might look like the following (a bit of an artificial example to demonstrate all 3 types at the same time):

alias Fledex.Component.Dot

led_strip :nested_components, Kino do
  animation :second,
    send_config: fn _triggers ->
      %{hour: _hour, minute: _minute, second: second} = Time.utc_now()
      %{offset: second, rotate_left: false}
    end do
    _triggers ->
      leds(60) |> light(:red)
  end

  component(:minute, Dot, color: :red, count: 60, trigger_name: :minute)
  component(:hour, Dot, color: :blue, count: 24, trigger_name: :hour)

  static :helper do
    leds(5) |> light(:davy_s_grey, offset: 5) |> repeat(12)
  end
end

You mainly use the functionality from Fledex.Leds which has plenty of functions. It allows to set individual leds, provides the possibility to nest led sequences, to repeat and to define leds through some functions, like gradients and rainbow distributions. Fledex.Color.Names provides a very rich set of predefined color names, but you can define it also by specifying a hex value. Here an example of an led squence of 10 leds with the first 3 being red, green, and 0x0000ff (blue). The rest will be black (off).

  leds(10) |> red() |> light(:green) |> light(0x0000ff)

There is also a rich set of support functionality to make the definition of LED strips (and especially animations) easier, like:

• Fledex.Effect.* to define some effects (like Dimming, Wanish, ...) on a sequence of leds
• Fledex.job to define repetitive tasks, like fetching some weather information

Take a look at the Livebook examples on how to use the DSL. Note: the livebooks do present also the internals how the library works. As a first step you can skip those.

Livebook

As mentioned above, the library works well in conjunction with Livebook so you probably want to take your first steps with it. You can find some livebooks files that show you how to use the library in a notebook (with and without hardware). You should be able to do most of your development on a computer (emulating the LED strip with a Fledex.Driver.Impl.Kino) before adjusting it to the real hardware (with the Fledex.Driver.Impl.Spi). On real hardware you can even run it with serveral drivers at the same time.

Nerves-Livebook

TODO: Add more info...

Further Docs

you can find some further documentation in the docs folder about:

• An Overview over the Architecture
• How to setup and connect real Hardware
• You might find in the folder also some temporary documenation with some thoughts, but I delete them again, once they have fulfilled their purpose, except for:
• A bit of history with the Project Plan as created with my son, since it's a nostalgic document

Known Limitations

If you want to run this library in nerves-livebook, you currently have to compile your own livebook with the library included in your mix.exs file, since you can't add any libraries that are not already bundled.

Contributing

Contributions of any kind are very much welcome

• raising issues,
• raising PR (see also this doc),
• reporting security vulnerabilities (see also this doc),
• suggesting improvements to documentation incl. reporting typos,
• raising feature requests,
• ...

Before doing so please make sure to also read through the CONTRIBUTING document and ensure to follow the Code of Conduct.

If you need any assistance, feel free to send an email to fledex at reik.org