Fledex.Driver.Interface behaviour (fledex v0.5.0)

View Source

A driver dispatches the "real" hardware. Differen types of drivers exist. Currently the following drivers exist:

  • Null: a driver that doesn't do anything. This is the default driver. It's also very practical for tests.
  • Logger: a driver that logs the led data to the terminal or to the logs
  • Kino: a driver that can display the LEDs in a livebook
  • Spi: a driver that can connect to a real LED strip with a WS2801 chip.
  • PubSub: a driver that can transfer the LED data via pubsub. This should also allow the data to be transferred to a LED strip connected on another computer.

More Drivers can be created by implementing this simple behaviour

Summary

Callbacks

This callback will be called to retrieve the default set of parameters for this driver. It will be used as default and then ovelayed with the additional arguments passed in (which can be passed in to the function)

The init function will be called after the Fledex.LedStrip is initialized as part of the initialization process. A map of initalization arguments are passed to the driver. The driver can decide what to do with them. The returned map is a configuration that gets passed to any of the other driver functions.

In some cases it is necessary to reinitialize the driver when a new LED strip is defined (see the Fledex.Driver.Impl.Kino as an example). The driver should know whether it needs to do anything or not. If it does not need to do anything, then simply return the passed in keyword list, i.e.

THe terminate functions gets called when we dispose of the led strip. This the place where the driver can perform some cleanup (e.g.: close some channels)

This is the main function where we transfer the LED information to the "hardware" The leds is a list of integers, (color codes of the form 0xrrggbb if written in hexadecimal format). The counter is a counter that gets incremented in each update loop and thereby allows to transfer the data with a lower frequency by not transferring it in every loop. The module_config is the config that got returned by the init/1 or reinit/1 functions

Callbacks

configure(keyword)

@callback configure(keyword()) :: keyword()

This callback will be called to retrieve the default set of parameters for this driver. It will be used as default and then ovelayed with the additional arguments passed in (which can be passed in to the function)

init(module_init_args)

@callback init(module_init_args :: keyword()) :: keyword()

The init function will be called after the Fledex.LedStrip is initialized as part of the initialization process. A map of initalization arguments are passed to the driver. The driver can decide what to do with them. The returned map is a configuration that gets passed to any of the other driver functions.

reinit(old_module_config, new_module_config)

@callback reinit(old_module_config :: keyword(), new_module_config :: keyword()) ::
  keyword()

In some cases it is necessary to reinitialize the driver when a new LED strip is defined (see the Fledex.Driver.Impl.Kino as an example). The driver should know whether it needs to do anything or not. If it does not need to do anything, then simply return the passed in keyword list, i.e.:

def reinit(_old_module_config, new_module_config), do: new_module_config

terminate(reason, config)

@callback terminate(reason, config :: keyword()) :: :ok
when reason: :normal | :shutdown | {:shutdown, term()} | term()

THe terminate functions gets called when we dispose of the led strip. This the place where the driver can perform some cleanup (e.g.: close some channels)

transfer(leds, counter, config)

@callback transfer(
  leds :: [Fledex.Color.Types.colorint()],
  counter :: pos_integer(),
  config :: keyword()
) ::
  {config :: keyword(), response :: any()}

This is the main function where we transfer the LED information to the "hardware" The leds is a list of integers, (color codes of the form 0xrrggbb if written in hexadecimal format). The counter is a counter that gets incremented in each update loop and thereby allows to transfer the data with a lower frequency by not transferring it in every loop. The module_config is the config that got returned by the init/1 or reinit/1 functions