@spec __using__(keyword()) :: Macro.t()

By use-ing this module, the Fledex macros are made available.

This macro does also import Fledex.Leds, Crontab.CronExpression, Fledex.Utils.PubSub, and all the colors specified (see also the :colors option). Therefore the functions from those modules are directly available without namespace.

In addition the drivers (part of the FledexDriver.Impl namespace) are aliased.

Take a look at the various livebook examples for more details on how to use the Fledex library and macros.

Options

When calling use Fledex you can specify a couple of options:

• :dont_start: If true is specified this will prevent the Fledex.Supervisor.AnimationSystem from being started. In this case the :supervisor option has no effect.

  Note

  This will not stop the AnimationSystem if it was already started by someone else.

• :supervisor: specifies how we want to supervise it. See the Supervisor section for more details.
• :log_level: specifies the log level. This is important if none is already specified in a config file.
• :colors: defines the colors that should be imported (i.e can be called without namespace). See the Colors section for more details.

Supervisor

The options for the :supervisor are:

• :none: Contrary to the :dont_start option, this will start the Fledex.Supervisor.AnimationSystem but without hanging it into a supervision tree. This is the default.
• :app: We add the Fledex.Supervisor.AnimationSystem to the application supervisr. You need to ensure that you have started the fledex application (done automatically if you run iex -S mix from the fledex project)
• :kino: The Fledex.Supervisor.AnimationSystem will be added to the Kino session supervisor. The AnimationSystem will terminate when the livebook session terminates.
• {:dynamic, name}: The Fledex.Supervisor.AnimationSystem will be added as a child process to the DynamicSupervisor with the given name.

Colors

The options for the :colors option can be both a single term (atom or module) or a list thereof. When an atom is specified it will be translated to the appropriate module(s), see below. If a module is specified it needs to adhere to the Fledex.Color.Names.Interface behaviour and will be loaded.

When several color modules are specified they will all be imported (except imports: false is specified)

The following color shortcuts exist (see also Fledex.Config.known_color_modules/0):

• :css: This will load Fledex.Color.Names.CSS
• :ral: This will load Fledex.Color.Names.RAL
• :svg: This will load Fledex.Color.Names.SVG
• :wiki: This will load Fledex.Color.Names.Wiki
• :all: This will load all the above colors
• :none: no colors will be imported
• :default: this will load the default set of colors marked as :core (:wiki, :css, :svg). This is also the default, i.e. when you do not specify the :colors option.

alias Fledex.Leds
alias Fledex.Color.Names.RAL

Leds.new(10)
  |> Leds.light(RAL.sunset_red())
  |> Leds.light(RAL.sunset_red(:hex))
  |> Leds.light(RAL.sunset_red(:rgb))
  |> RAL.sunset_red()

use Fledex, colors: :wiki
leds(1) |> blue()
use Fledex, colors: :css
leds(1) |> blue()

error: function blue/1 imported from both Fledex.Color.Names.CSS and Fledex.Color.Names.Wiki, call is ambiguous
└─ iex:4

** (CompileError) cannot compile code (errors have been logged)

This introduces a new animation that will be played over and over again until it is changed.

Therefore we give it a name to know whether it changes. The do ... end block needs to define a function. This function receives a trigger as argument, but you have two possbilities to implement it.

• Either you pattern match on the triggers, e.g. something like the following:

  led_strip :strip, Kino do
  animation :name do
    %{strip: counter} ->
      do_something_with_the_counter(counter)
    triggers ->
      # During init it can happen that the strip trigger is not available yet
      do_something_during init_phase(triggers)
  end
  end

• Or, if you don't require the trigger, you can specify it without a trigger, e.g.

  led_strip :strip, Kino do
  animation :name do
    do_something_without_a_trigger()
  end
  end

@spec component(atom(), module(), keyword()) :: Fledex.Animation.Manager.config_t()

A component is a pre-defined animation that reacts to some input. We might have a thermometer component that defines the display of a thermometer:

• input: single value
• display is a range (positive, 0, negative)
• ...

A component does not have a do ... end block, since it defines it's own animation(s), and it's only controlled through some parameters that can be passed as options like:

• the value,
• the display colors,
• the range of our scale

Thus, our component would look like the following:

  alias Fledex.Component.Thermometer
  component :thermo, Thermometer,
    range: -20..40,
    trigger: :temperature,
    negative: :blue,
    null: :may_green,
    positive: :red

It is up to each component to define their own set of mandatory and optional parameters.

This introduces a new coordinator.

A coordinator is a component that receives events from the different animations and effects and can react to them (e.g. enabling or disabling animations and effects).

Each coordinator is identified by a name and implements a state machine in its do ... end block. Probably the best way to do this is through pattern matching. On the broadcastet state, the context (information on who emitted it) and some coordinator state.

Add an effect to an animation

This macro allows to add an effect to an animation (or even a component (TODO: figure out whether an effect on a static component makes any sense, it would mean that the static component suddenly would need to be animated)

You simply warp the animation inside a effect block. It's possible to have severeal nested effects. In that case they will all be executed in sequence.

Example:

use Fledex
alias Fledex.Effect.Wanish
led_strip :john, Kino do
  effect Wanish, trigger_name: :john do
    animation :test do
      _triggers ->
        leds(1) |> light(:red) |> repeat(50)
    end
  end
end

A job is a cron job that will trigger in regular intervals (depending on the schedule specified). You can run any function and the most likely event you will trigger is to publish an event to the triggers (see the weather example livebook):

  broadcast_trigger(%{temperature: -15.2})

Each job consists of:

• name- a unique name
• schedule- a cron pattern or an interval (as specified in this cheatsheet). Note: Crontab.CronExpression gets imported and therefore the sigil can directly be used, i.e. ~e[* * * * * * * *]e. An interval is specified with as tuple with an amount and a unit {10, :min}. See fledex_scheduler for more details
• options- a keyword list with some options. The following options exist:
  • :run_once- a boolean that indicates whether the job should be run once at creation time. This can be important, because you might otherwise have to wait for an extended time before the function will be executed.
  • :timezone- The timezone the cron pattern applies to. If nothing is specified "Etc/UTC" is assumed. Make sure that the tzdata dependency is specified to use other timezones
  • :overlap- This indicates whether jobs should overlap or not. An overlap can happen when running the job takes more time than the interval between job runs. For safety reason the default is false.
• :do - a block of code that should be executed. You can specify directly your code here. It will be wrapped into an anonymous function.

Example:

use Fledex
led_strip :nested_components2, Kino do
  job :clock, ~e[@secondly]e do
    date_time = DateTime.utc_now()

    broadcast_trigger(%{
      clock_hour: date_time.hour,
      clock_minute: date_time.minute,
      clock_second: date_time.second
    })
  end
end

This introduces a new led_strip.

The drivers can be spcified in 3 different ways:

• just a driver module (like Spi). In this case the default settings will be used
• a driver module with it's configuration (like {Spi, [dev: "spidev0.1"]})
• or a set of drivers (always with their configuration), like: [{Spi, []}, {Spi, [dev: "spidev0.1"}]

A set of default drivers exist for conenience that can be used like Spi, Null, ... (see Fledex.LedStrip for details).

A special driver :config exists that will simply return the converted dsl to the corresponding configuration. This can be very convenient for

• running tests
• implementing components consisting of several animations. Take a look at the Fledex.Component.Clock as an example.

The strip_options configures any non-driver specific settings of the strip (like how often the strip should be repainted, how different animations should be merged, ...).

The static macro is equal to the animation macro, but it will not receive any triggers.

Therefore, there will not be any repainting and the def_func will not receive any parameter. It will only be painted once at definition time.

@spec version() :: String.t()

Returns the version of the Fledex library. It can be important to know the version in order to adjust some code depending on the version