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

Copy Markdown View Source

This interface defines the @behaviour for drivers. They can be dummy implementations like a driver that dumps the output to IO, wich can be useful for testing without real hardware. A proper implementation probably opens a channel (if not already open) to the bus (like SPI) and sends the data to the bus.

Different types of drivers exist. Currently the following 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.Ws2801: a driver that can connect to a real LED strip with a WS2801 chip.
  • Spi.Ws2812: a driver that can connect to a real LED strip with a WS2812 chip.
  • PubSub: a driver that can transfer the LED data via pubsub. This should also allow the data to be transferred to an LED strip connected on another computer.

More Drivers can be created by implementing this simple behaviour

Note

The implementing module is allowed to store information in the state (like the channel it has oppened), so that we don't have open/close it all the time. Cleanup should happen in the terminate function

Summary

Callbacks

change_config(old_module_config, new_module_config, global_config)

In some cases it is necessary to change the config when a new LED strip is defined. 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.

configure(keyword)

This callback will be called to retrieve the default set of parameters for this driver.

init(module_config, global_config)

The init function will be called after the Fledex.LedStrip is initialized as part of the initialization process.

terminate(reason, config)

The terminate functions gets called when we dispose of the led strip.

transfer(leds, counter, config)

This is the main function where we transfer the LED information to the "hardware".

Callbacks

change_config(old_module_config, new_module_config, global_config)

@callback change_config(
  old_module_config :: keyword(),
  new_module_config :: keyword(),
  global_config :: map()
) :: keyword()

In some cases it is necessary to change the config when a new LED strip is defined. 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 change_config(_old_module_config, new_module_config, _global_config), do: new_module_config

(see Fledex.Driver.Impl.Kino as an example).

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_config, global_config)

@callback init(module_config :: keyword(), global_config :: map()) :: 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.

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/2 or change_config/3 functions