Fixing all the livebooks to work well with the 0.7 release

Updating the TODOs

Author: maze

TODO.md

@@ -16,7 +16,7 @@ Even though this library is published, there are things I still want to do befor
   - [x] Document the driver options (v0.7)
   - [x] Update the cheatsheet with coordinator info (v0.7)
   - [x] Resolve all important `doctor` issues (v0.7)
-  - [ ] Add a livebook with coordinator examples (v0.7) <-- WIP
+  - [ ] Add a livebook with coordinator examples (v0.8) <-- WIP
   - [ ] Update documentation with the Supervision tree (v0.8)
   - [ ] hardware setup (analogy with a bus letting 24 passangers off the bus at every led-bus-stop). Create a comprehensive write-up (v0.8)
 - [ ] Testing
@@ -45,7 +45,8 @@ Even though this library is published, there are things I still want to do befor
   - [x] Rename the job property `pattern` to `schedule` in the DSL created config (v0.7)
   - [x] The refactoring made the debug_logging property unnecessary. It's unclear on what to do with it. (v0.7)
   - [x] Rename `docs` to `pages`. Some people find it confusing to have a `docs` and a `doc` (created by `ex_doc`) (v0.7)
-  - [ ] Make sure that all the job options are correctly honored (adjust documentation if necessary) (v0.7)
+  - [ ] We should be able to replace the `Animation.Manager` config splitting with the `Enum.group_by` function (v0.8)
+  - [ ] Make sure that all the job options are correctly honored (adjust documentation if necessary) (v0.8)
   - [ ] Rethink whether we really want to create a `Fledex.Config.Data` module or we should store the information in a GenServer. The issue with the GenServer is that we need to start a server. But maybe that's not soo bad. (v0.9)
   - [x] Change the `start_links` to take just one arg (the parameters) and an `opts` passed as opts to GenServer. Through this we define the name and therefore can move the `via_tuple` outside of the modules.
 - [ ] Missing functionality
@@ -54,13 +55,13 @@ Even though this library is published, there are things I still want to do befor
   - [x] Allow color modules to not carry more information than just a pre-defined set (v0.7)
   - [x] convert the rgb to other color spaces (in the various color name modules). Considering the previous point we might not need to do this, because it should now be optional (v0.7) <-- reduced the generated color functions, and what gets exposed
   - [x] we start things through the Supervisor, but we don't shut things down through it (v0.7)
-  - [ ] Put some more effort into the coordinator to make it work well (v0.7)
   - [x] Rework the `:job` implementation (v0.7):
     - [x] The Job should (at least appear) to be connected to the LedStrip
     - [x] Replace it with a different library (maybe `SchedEx`? https://hexdocs.pm/sched_ex/readme.html) (v0.7)
       - [x] Investigate various libraries and how they fit into Fledex. I looked at various different libraries (`erlcron`, `sched_ex`, `exq_scheduler`, `ecron`, ...), but none really fulfils the needs :-( `SchedEx` is the one that is simple and comes closest. Therefore the plan is to take it (it's MIT license), modify it, and integrate it into Fledex
       - [x] It's not possible to inject a context to the job, because you either have to provide an `{M, F, [Args]}` or a `(-> any())` function. The former is not possible, since we don't have amodule (but just an anonymous function) and the latter is not possible, because we can't pass in any argument :-(. We would need to extend Quantum to accept an {F, [Args]}
       - [x] Switch to a released version of `:fledex_scheduler` (v0.7)
+  - [ ] Put some more effort into the coordinator to make it work well (v0.8)
   - [ ] Enable Telemetry? (v0.8)
     - [ ] Switch also the `fledex_scheduler` stats to telemetry (v0.8)
   - [ ] Add support for WS2811/12/13/14/15 LED strips controlled through phase modulation. (v0.8)

lib/fledex/animation/animator.ex

@@ -198,10 +198,22 @@ defmodule Fledex.Animation.Animator do
 
   @impl GenServer
   @spec handle_cast({:change_config, config_t}, state_t) :: {:noreply, state_t}
-  def handle_cast({:change_config, config}, state) do
-    state = do_update_config(state, config)
+  def handle_cast(
+        {:change_config, config},
+        %{strip_name: strip_name, animation_name: animation_name} = state
+      ) do
+    Logger.debug(
+      "changing animation: #{inspect({strip_name, animation_name, self()})}",
+      Map.filter(state, fn {key, _val} ->
+        key in [:strip_name, :strip_server, :animation_name, :type]
+      end)
+    )
 
-    {:noreply, update_leds(state)}
+    state = state
+      |> do_update_config(config)
+      |> update_leds()
+
+    {:noreply, state}
   end
 
   @impl GenServer

livebooks/2_fledex_first_steps.livemd

@@ -56,11 +56,12 @@ Now we are ready to send some data to the led_strip. Before we send some color i
 For now we use a hex code to define colors. You can learn more about colors and how to define them in [chapter 3b](3b_fledex_everything_about_colors.livemd).
 
 ```elixir
-LedStrip.define_namespace(:john, :default)
-LedStrip.set_leds(:john, :default, [0xFF0000, 0x00FF00, 0x0000FF], 3)
+server = AnimationSystem.get_strip_server(:john)
+LedStrip.define_namespace(server, :default)
+LedStrip.set_leds(server, :default, [0xFF0000, 0x00FF00, 0x0000FF], 3)
 ```
 
-> #### Note {: .info}
+> #### Note
 > 
 > If you don't see your led strip displayed, then you might have to scroll up a bit. It
 > should be just after the code block where you defined your led_strip.
@@ -74,23 +75,25 @@ All functions are trying to create a simple animation by configuring the leds, s
 ```elixir
 defmodule Helpers do
   def red(namespace) do
+    server = AnimationSystem.get_strip_server(:john)
     Enum.each(1..10, fn _index ->
-      LedStrip.set_leds(:john, namespace, [0xFF0000, 0x000000, 0x000000, 0x000000, 0x000000], 5)
+      LedStrip.set_leds(server, namespace, [0xFF0000, 0x000000, 0x000000, 0x000000, 0x000000], 5)
       Process.sleep(600)
-      LedStrip.set_leds(:john, namespace, [0x000000, 0xFF0000, 0x000000, 0x000000, 0x000000], 5)
+      LedStrip.set_leds(server, namespace, [0x000000, 0xFF0000, 0x000000, 0x000000, 0x000000], 5)
       Process.sleep(600)
-      LedStrip.set_leds(:john, namespace, [0x000000, 0x000000, 0xFF0000, 0x000000, 0x000000], 5)
+      LedStrip.set_leds(server, namespace, [0x000000, 0x000000, 0xFF0000, 0x000000, 0x000000], 5)
       Process.sleep(600)
-      LedStrip.set_leds(:john, namespace, [0x000000, 0x000000, 0x000000, 0xFF0000, 0x000000], 5)
+      LedStrip.set_leds(server, namespace, [0x000000, 0x000000, 0x000000, 0xFF0000, 0x000000], 5)
       Process.sleep(600)
-      LedStrip.set_leds(:john, namespace, [0x000000, 0x000000, 0x000000, 0x000000, 0xFF0000], 5)
+      LedStrip.set_leds(server, namespace, [0x000000, 0x000000, 0x000000, 0x000000, 0xFF0000], 5)
       Process.sleep(600)
     end)
   end
 
   def blue(namespace) do
+    server = AnimationSystem.get_strip_server(:john)
     Enum.each(1..10, fn _index ->
-      LedStrip.set_leds(:john, namespace, [
+      LedStrip.set_leds(server, namespace, [
         0x000000,
         0x000000,
         0x000000,
@@ -101,7 +104,7 @@ defmodule Helpers do
 
       Process.sleep(600)
 
-      LedStrip.set_leds(:john, namespace, [
+      LedStrip.set_leds(server, namespace, [
         0x000000,
         0x000000,
         0x000000,
@@ -112,7 +115,7 @@ defmodule Helpers do
 
       Process.sleep(600)
 
-      LedStrip.set_leds(:john, namespace, [
+      LedStrip.set_leds(server, namespace, [
         0x000000,
         0x000000,
         0x0000FF,
@@ -123,7 +126,7 @@ defmodule Helpers do
 
       Process.sleep(600)
 
-      LedStrip.set_leds(:john, namespace, [
+      LedStrip.set_leds(server, namespace, [
         0x000000,
         0x0000FF,
         0x000000,
@@ -134,7 +137,7 @@ defmodule Helpers do
 
       Process.sleep(600)
 
-      LedStrip.set_leds(:john, namespace, [
+      LedStrip.set_leds(server, namespace, [
         0x0000FF,
         0x000000,
         0x000000,
@@ -148,14 +151,15 @@ defmodule Helpers do
   end
 
   def rainbow(namespace) do
+    server = AnimationSystem.get_strip_server(:john)
     Enum.each(0..10000, fn index ->
       config = [
         num_leds: 50,
         reversed: true
       ]
 
       Leds.leds(50)
-      |> Leds.set_led_strip_info(:john, namespace)
+      |> Leds.set_led_strip_info(server, namespace)
       |> Leds.rainbow(config)
       |> Leds.send(offset: index)
 
@@ -165,9 +169,10 @@ defmodule Helpers do
   end
 
   def gradient(namespace) do
+    server = AnimationSystem.get_strip_server(:john)
     Enum.each(0..10000, fn index ->
       Leds.leds(50)
-      |> Leds.set_led_strip_info(:john, namespace)
+      |> Leds.set_led_strip_info(server, namespace)
       |> Leds.gradient(0xFF0000, 0x0000FF, %{num_leds: 50})
       |> Leds.send(
         offset: index,
@@ -189,12 +194,12 @@ Take note, that our functions create sequences of different length.
 
 Now we can try it out with one of the first functions.  Let's call our `red/1` function. We spawn it in  a separate process. The reason for that you'll see in a second.
 
-> #### Note {: .info} 
+> #### Note
 > 
 > You might have to scroll up to see the animation
 
 ```elixir
-LedStrip.define_namespace(:john, :red)
+LedStrip.define_namespace(server, :red)
 
 spawn(fn ->
   Helpers.red(:red)
@@ -203,14 +208,14 @@ end)
 
 Similarly you can do the same with the `blue/1` function. Where it gets interesting is, when you start first the red function and then start the blue function while the red function is still running.
 
-> #### Note {: .info} 
+> #### Note
 > 
 > Don't forget to use a differnt namespace name compared to the above function, otherwise
 > one function would constantly overwrite what the other function has defined. We want them
 > to live in parallel and get merged.
 
 ```elixir
-LedStrip.define_namespace(:john, :blue)
+LedStrip.define_namespace(server, :blue)
 
 spawn(fn ->
   Helpers.blue(:blue)
@@ -226,7 +231,7 @@ While both functions are running, they will
 Now we can use the above functions with our trip. We can run the functions by spawning a new thread. This allows to also see what happens if another thread works in parallel. Here we create a rainbow effect that will be send with a changing offset so that the rainbow rotates through the LEDs
 
 ```elixir
-LedStrip.define_namespace(:john, :rainbow)
+LedStrip.define_namespace(server, :rainbow)
 spawn(fn -> Helpers.rainbow(:rainbow) end)
 ```
 
@@ -237,14 +242,14 @@ spawn(fn -> Helpers.rainbow(:rainbow) end)
 Here we create a gradient between red and blue. Also this one we let rotate through. Note, depending on whether you started the rainbow above or not, you might see different results. Try this section with and without running the Rainbow section.
 
 ```elixir
-LedStrip.define_namespace(:john, :gradient)
+LedStrip.define_namespace(server, :gradient)
 spawn(fn -> Helpers.gradient(:gradient) end)
 ```
 
 We can drop the namespaces to see what happens
 
 ```elixir
-LedStrip.drop_namespace(:john, :gradient)
+LedStrip.drop_namespace(server, :gradient)
 ```
 
 As we can see our animation stops to be visible and our calls to `set_leds` will fail (but we swallow those errors).
@@ -256,9 +261,9 @@ As we can see our animation stops to be visible and our calls to `set_leds` will
 This test is running a couple of different ligth definitions in parallel.
 
 ```elixir
-LedStrip.define_namespace(:john, :john)
-LedStrip.define_namespace(:john, :jane)
-LedStrip.define_namespace(:john, :default)
+LedStrip.define_namespace(server, :john)
+LedStrip.define_namespace(server, :jane)
+LedStrip.define_namespace(server, :default)
 
 spawn(fn -> Helpers.blue(:jane) end)
 spawn(fn -> Helpers.red(:john) end)

livebooks/3_fledex_animations.livemd

@@ -28,7 +28,12 @@ alias Fledex.Driver.Impl.Kino
 alias Fledex.Color.Correction
 alias Fledex.Supervisor.AnimationSystem
 
+# to use our color aliases (like :red) we need to configure them
+use Fledex.Config
+
+# now we start our animation system
 AnimationSystem.start_link()
+
 ```
 
 ## Helper functions
@@ -68,6 +73,7 @@ We call our led strip `:john`. In this example we will only use the simple kino
 We then define an animation configuration that consists of a map with the key being the name of the animation and the value being the configuration of that animation. Each animation configuration needs to specify the `:type` as `:animation`, because (as we will see later) other types exist, and a `:def_func` that defines our animation (potentially with an additional `:send_config_func` as shown here. We'll look at this in more detail in a later section).
 
 ```elixir
+
 Manager.register_strip(:john, [{Kino, []}], [])
 
 Manager.register_config(:john, %{

livebooks/3b_fledex_everything_about_colors.livemd

@@ -12,8 +12,6 @@ Mix.install([
 ])
 ```
 
-## Setup
-
 ## Colors and different drivers
 
 Different drivers have different color characteristics. Therefore you might have to adjust the colors when migrating from one output to another. Some drivers allow some color correction to try to adjust for those issues (see also the 'Color Correction' section.
@@ -34,7 +32,7 @@ We don't specify anything and thereby go with the default color set of `:wiki`,
 use Fledex
 ```
 
-Fledex has an extensive set of predefined colors from [Wikipedia](https://en.wikipedia.org/wiki/List_of_colors:_A%E2%80%93F), [CSS](https://drafts.csswg.org/css-color/#named-colors), [SVG](https://www.w3.org/TR/SVG11/types.html#ColorKeywords), and [RAL](https://en.wikipedia.org/wiki/List_of_RAL_colours).Apart from the last list (which is not so commonly used), they are all combined together to a single Names module. You can retrieve those names by calling:
+Fledex has an extensive set of predefined colors from [Wikipedia](https://en.wikipedia.org/wiki/List_of_colors:_A%E2%80%93F), [CSS](https://drafts.csswg.org/css-color/#named-colors), [SVG](https://www.w3.org/TR/SVG11/types.html#ColorKeywords), and [RAL](https://en.wikipedia.org/wiki/List_of_RAL_colours). Apart from the last list (which is not so commonly used), they are all combined together to a single Names module. You can retrieve those names by calling:
 
 <!-- livebook:{"force_markdown":true} -->
 
@@ -54,11 +52,17 @@ Fledex.Color.Names.info(name, :all)
 Here a list of all the defined colors (extra colors can still be used, but need to be called explicitly, like the RAL colors through `Fledex.Color.Names.RAL`):
 
 ```elixir
-colors = Enum.map(Fledex.Color.Names.names() |> Enum.sort(), fn name ->
-  Fledex.Color.Names.info(name, :all)
-  end)
+fields = [:descriptive_name, :name, :rgb, :hex, :source, :module]
+colors = Enum.map(
+  Fledex.Color.Names.names() |> Enum.sort(), 
+  fn name ->
+    Fledex.Color.Names.info(name, :all)
+    |> Map.take(fields)
+  end
+)
+
 Elixir.Kino.DataTable.new(colors,
-  keys: [:descriptive_name, :name, :rgb, :hex, :hsv, :hsl, :source, :module],
+  keys: [:descriptive_name, :name, :rgb, :hex, :source, :module],
   sorting_enabled: true
 )
 ```
@@ -108,9 +112,10 @@ Before we look at the Fledex features regarding color correction we first need t
 > the colors, making the whites appear white, the blacks appear black, and making sure that
 > everything is even.
 
-The color correction consists of two parts. First to compensate the physical mis-coloring of the LEDs. The basic colors on the classical 5050 LED chip are not shown in the same intensity. So we need to compensate this.
+The color correction consists of two parts:
 
-The second color coorection we might want to perform is to bring the color into the correct "temperature" (named due to the [black body radiator](https://en.wikipedia.org/wiki/Black-body_radiation)) with a relatively continuous spectrum, or approach the light of a gaseous light source with more discrete spectral band (see [gas discharge lamp](https://en.wikipedia.org/wiki/Gas-discharge_lamp)).
+1. First to compensate the physical mis-coloring of the LEDs. The basic colors on the classical 5050 LED chip are not shown in the same intensity. So we need to compensate this.
+2. The second color correction we might want to perform is to bring the color into the correct "temperature" (named due to the [black body radiator](https://en.wikipedia.org/wiki/Black-body_radiation)) with a relatively continuous spectrum, or approach the light of a gaseous light source with more discrete spectral band (see [gas discharge lamp](https://en.wikipedia.org/wiki/Gas-discharge_lamp)).
 
 Color correction is provided in Fledex through the modules under `Fledex.Color.Correction`.
 

livebooks/4_fledex_clock_example.livemd

@@ -18,8 +18,6 @@ alias Fledex.Leds
 alias Fledex.LedStrip
 alias Fledex.Supervisor.AnimationSystem
 
-AnimationSystem.start_link()
-
 :ok
 ```
 
@@ -32,7 +30,14 @@ But before we get there, we first initiate our led strip.
 
 ## Preparational steps
 
-First we register a strip (we name it `:clock`) with our `Fledex.Animation.Manager` and we use the default settings for the `Kino` driver.
+First we need to define our config and start our AnimationSystem
+
+```elixir
+use Fledex.Config
+AnimationSystem.start_link()
+```
+
+Then we register a strip (we name it `:clock`) with our `Fledex.Animation.Manager` and we use the default settings for the `Kino` driver.
 
 Then we modify the led strip to update with a very low frequency. Our clock only updates every second and therefore it's unnecessary that we update it more often than that. To avoid any issues due to some runtime delays, we update it twice every second. Thereby the second indicator will never jump an led.
 

livebooks/5_fledex_weather_example.livemd

@@ -21,9 +21,6 @@ alias Fledex.Color.Correction
 alias Fledex.Utils.PubSub
 alias Fledex.Supervisor.AnimationSystem
 
-AnimationSystem.start_link()
-
-
 :ok
 ```
 
@@ -67,6 +64,13 @@ As can be seen we get the information we are interested in, the current temperat
 
 ## Configuring the led strip
 
+Again, we configure our System and start our AnimationSystem
+
+```elixir
+use Fledex.Config
+AnimationSystem.start_link()
+```
+
 Now it's time to prepare our led strip. First we define our strip and we set a very low refresh rate. An update every 10 sec is enough.
 
 ```elixir

livebooks/8_fledex_component.livemd

@@ -50,7 +50,7 @@ end
 To test our animation we fake again the temperature by simply publishing the desired temperature.
 
 ```elixir
-Fledex.Utils.PubSub.broadcast(:fledex, "trigger", {:trigger, %{temperature: 17.2}})
+broadcast_trigger(%{temperature: 17.2})
 ```
 
 ## What is a component
@@ -96,11 +96,11 @@ The interesting thing in the `Fledex.Component.Dot` component is that it actuall
 
 but that almost equal to importing.
 
-  > #### Note {: .info}
-  > 
-  > We want to leave the definition of color names to the user of our component. In a component you
-  > should ideally define colors as hex values and not by name. If you still want to use color
-  > names, then specify the color name module explicitly (example: `Fledex.Color.Names.Wiki.red()`)
+> #### Note
+> 
+> We want to leave the definition of color names to the user of our component. In a component you
+> should ideally define colors as hex values and not by name. If you still want to use color
+> names, then specify the color name module explicitly (example: `Fledex.Color.Names.Wiki.red()`)
 
 The code looks like the following