Happy New Year

The intention was to improve the coordinator for this release, but this did not happen. So many changes have collected that its' really time for a new release. What better time to make it than to start off the new year?

This release breaks (again) quite a few APIs, but the DSL should not be impacted by it. That's the one you really should be using. Hence I decided to not put a BC (=Backward Compatibility) breaking warning this time (except if you look at the details below :-)).

Here are the changes for this release

Flexible colors (#71, #78 and others)

This is a major change in how we load the color name modules. Instead of importing them into Fledex.Color.Names module, we now load the specific modules making sure that only those functions are loaded that are not conflicting.

This allows to

use Fledex, colors: [:wiki, :ral, MyOwnColorDefinitions]

Fledex.Color.Names is now not generated anymore, but we use the new Fledex.Config to access the configured colors. It generate the Fledex.Config.Data that is internal to it. When use FLedex.Config you have the option to decide on whether you want to import
the configured colors or not.

Note {: .info}

When you use Fledex the colors will be imported by default (but you can specify imports: false as option), When you use Fledex.Config the colors will not be imported by default, but you can specify imports: true as option.

Since Fledex.Color.Names does not expose the colors directly anymore, the documentation got broken. Therefore a new mix task mix docs.fledex.colors generates a markdown page with all the colors of all the known color modules and got integrated into the mix docs process so it will be automatically generated for the documentation. This now also includes the Fledex.Color.Names.RAL colors.

All color name modules are now following the same behaviour Fledex.Color.Names.Interface

Warning: {:.warning}

This breaks a couple of things, namely the Fledex.Color.Names module.
use Fledex several times might redefine the colors that are getting imported and should be avoided.
Therefore components should also import Fledex if they want to use the macros, instead of use Fledex (This does mean that you would need to be explicit on all the other module names (Leds, color names, ...), but that's rather a good thing.

Related changes

As part of this refactoring a lot of smaller refactorings happened at the same time within the color related modules:

• With the new color handling and the new mix task we don't have a need for the custom ex_doc version anymore.
• Changed the color_name_t to allow any atom as type and most fields are optional
• Removed the most color functions from the color modules. We now only expose :hex, :name, and :module. The rest of the information is still present but can not be called directly. thus, you can't do color_name(:rgb) anymore. You can still do info(:color_name, :rgb) to retrieve the information.
• Adapted the Fledex.Color protocol implementation for atoms.
• The Fledex.Color protocol now only exposes a single function to_colorint/1. to_rgb/1 has been removed.
• Renamed Fledex.Color.Names.Dsl to Fledex.Color.Names.ModuleGenerator to better reflect it's purpose.
• The type color_struct_t has been extended to allow an arbitrary number of fields and most fields are optional (except the :hex and :name values).
• The Fledex.Color.Names.ModuleGenerator can now be configured to only create a set of functions (with the fields option) instead of exposing all fields directly. Other color properties can still be retrieved through color_name(what), but it will be an indirection to info(:color_name, what). Thus, you could use info/1 or info/2 also directly.
• Removed the properties from the color name modules that are not "natural" (now that we can do it)
• The Fledex.Color.Names.ModuleGenerator has been cleaned up and got added documentation
• updated the documentation and livebooks
• integrating the color guards into the color names module
• Renamed some functions in Fledex.Color.Names.LoadUtils to make their purpose more clear
• Adding a module for HSV, HSL, RGB. Fledex.Color.HSV and Fledex.Color.HSL are now used instead of a triples. The goal is that triples are reserved for RGBs). For consistency also introduced a Fledex.Color.RGB.
• Removed Fledex.Color.to_rgb/1. use Fledex.Color.RGB.to_tuple(color) instead
• Cleaning up and restructuring the conversion modules

Cleanup and improved API docs (#64, #83 and others)

BIG documentation improvement and cleanups including (also through other commits):

• Added and improved the API documentation (@specs, @moduledoc, and @docs)
• Restructured the API documentation to make the more useful information easier accessible
• Fixed the copyright headers
• Fixed the licenses so we are now FSF compliant. This required to replaced the cone_response picture with a version under a different license.
• Fixed also the License file issue to satisfy the scorecard tool. The overall license is now explicitly mentioned instead of being a link.
• Improved the README.md
• Updated the CREDITS.md file
• Minor improvements to the livebooks for the school (German). This is still WIP
• Added information about color correction to the 3b livebook
• Added API documentation for the conversion functions
• Updated the cheatsheet with coordinator information
• worked on the coordinator livebook (WIP)
• Documented the effect options
• Documented the driver options
• Moved the extra documentation from docs to pages (to make it less confusing with the generated api documentation by ex_doc that will end up in doc)

Improved Supervision tree (#84, #110)

The supervision tree has been improved.

• The AnimationSystem got some more functions (start_led_strip/4, led_strip_exists?/1, get_led_strips/0, reconfigure_led_strip/3, stop_led_strip/1) and the LedStripSupervisor got them as well (start_worker/5, worker_exists?/3, get_workers/2, reconfigure_worker/4, stop_worker/3)
• Some utility functions got created and moved around to support the above functions
• Replaced Quantum as a job scheduler with a heavily modified version of SchedEx (pulled in as a dependency. The fork can be found as Fledex_Scheduler)
• Reworked the Supervision Tree. The jobs are now properly attached to the LedStrip. Also changed how the process naming is done so it's limited to the supervisors and the manager. Nobody else is aware of process names and the registry.

Other changes

Bugs

• Fixed a documentation bug. The hue value in HSV is a byte representing 360 degrees.
• Fixed a bug in the Fledex.Supervisor.AnimationSystem that prevented options to be passed correctly to the Manager. This only became apparent with 2 or more options.
• Fixed a bug in LoadUtils.a2b/1 The value wasn't truncated to an integer
• Fixed a bug that the Fledex.Color protocol for `Fledex.Color.RGB didn't work in the livebook. Repositioning it solved the issue. Not sure why.

Cleanup

• Renamed some modules to make their purpose more clear
• Changed the > **Notes** (and similar) to > #### Note {: .info} to be consistent and in accordance with the recommendation in the ex_unit documentation even though it does "break" things on github.
• Cleanued up the Supervisor.Utils (combined functions)
• Cleaned up the Animation.Manager (combined functions)
• Changed LedStrip.reinit to change_config (including the drivers). Changed the LedStrip.change_config to change_global_config because it only changes the global settings and not the drivers.
• Renamed the Job pattern to schedule (since it now also allows intervals)
• Aligned the various function names that changed the config to change_config (instead of update_, change_, config).
• Renamed WikiUtils to Wiki.Converter and removed the filename function which is not necessary anymore

Depedendencies

• upgrading all dependencies to latest version
• Added tzdata as an optional dependency

Build

• Adding expert to the .gitignore exclusion list
• updated the max xref, since we have less compile connected files
• Made credo more strict. enabled all checks that I consider as reasonable and fixed the resulting issues.
• Adding support for Elixir 1.19. The latest Elixir version also helped to also reduce the max xref (9 --> 7)
• Made the latest version to run extra tests like formatting, xref, coverage instead of doing it on all versions (since the different versions have different behaviors)
• added ex_check, doctor, mix_audit, sobelow and configured ex_check to run all tests.
• changed excoveralls to create html and json output so that we can use the same mix check and to then upload the coverage result.
• Using ex_check in the CI pipeline (github action)

Security

• Fixed a directory traversal issue (even though I don't think it could be exploited since it's at c

Summer release

Caution

Several BC breaking changes are in this version, but most of them shouldn't impact the user of the DSL. You might be
impacted if you work with more lower level APIs (like some of the livebooks do and therefore required small adjustments.

• the parameters of Leds.set_led_strip_info/3 are around, so it's more consistent
• added a count to the set_leds (and set_leds_with_rotation) to optimize the call. It's allowed to be nil
• the animation type is now mandatory
• renamed several functions
• several functions got moved to other modules or deleted

It should be rather obvious which changes will break compatibility and it should be clear on how to fix it

Intro

In this a lot of things have changed to improve the stability and the quality of the code. The whole system now hangs in a supervision tree and processes get restarted if they start to fail for some reason. There are still some more changes expected but the biggest junk is done, so it's time for this summer release.

Note: The expected changes in the Effects did not happen in this version, this is on the plan for the next version as part of the further improvements of the Coordinator

What's new?

Features

• started all the processes in a Supervisor tree:
  • Built the AnimationSystem supervisor with Animation.Manager, LedStrips, Animation.JobScheduler, ...
  • Attached the Animation.Animator and Animation.Coordinator to the LedStrip
  • provided the possibility to specify a :supervisor option in the use Fledex call
  • Note: more smaller changes are expected in the next version, like introducing a stop_xyz to the supervisors, move the job scheduler to the LedStrip, ...
• removed the dependency from Animator onto the Leds.send function. We introduced a LedStrip.set_leds_with_rotation function.
• Animation.Animator options are now allowed to be nil
• added a :log_level parameter to use Fledex because the Fledex config might not be read if not started as an application. The default is to only log info levels and above

Docs

• big overhaul and restructuring of the documentation.
• added more documentation (@moduledoc, @typedoc, @doc) and improvement of livebooks
• added more livebooks for school presentation (in German, WIP)
• started to write some documentation for the coordinator (WIP)
• started using a modified ex_doc version to get the documentation working as desired (see elixir-lang/ex_doc#2118 for details)
• added favicon and logo to the documentation

Tests

• added more negative tests (especially related to the supervisor tree)
• simplified some tests (a result of introducing the supervisor tree)
• improved the stability of the tests

Builds

• added support for Elixir 1.18
  • small refactoring how the colors are stored that avoid the failing compilation (due to too expensive color compilation)
  • fixed some warnings that are emitted by the Elixir 1.18 compiler
• decided on the versions to support and test for.
• updated dependencies
• added scorecard analysis
• added OpenSSF Best Practices
• reduced the compile time dependencies

Bugs

• corrected some copyright notices (they had the wrong year)

Cleanups

• renamed shutdown functions to stop to be consistent
• moved several files/functions/... around and removed unnecessary stuff
• moved functions around so there is more consistency
• improved the @specs
  • added them wherever they were missing
  • simplified them by introducing new types
  • corrected them where erroneous (dialyzer does not report any issues anymore)
  • renamed them (like Manager.configs_t to Manager.config_t)
• moved all TODOs into the TODO.md file. Thereby, Credo now reports as found no issues
• cleaned up the IO.puts and replaced them with Logger entries where necessary. Especially logging process start and shutdown
• removed unused code
• removed the optional qualifier from the type spec where they are required
• breaking out the utility functions used in components
• fixing the component interface that any manager config is valid (not just animations)
• getting rid of the AnimatorBase and the AnimatorInterface (they weren't necessary and made things more complicated than necessary)
• made the animation type mandatory. The use of a default made things more fragile.

Final words

For the next release, as partially mentioned above, I'm looking at:

• further improvements and documentation for the Coordinator, including the changes on the Effects.
• improving the documentation for the school material
• improving the Supervisor tree (to get the JobScheduler as a part of the LedStrip (and maybe exchange Quantum for another library, maybe even one with millisecond precision?)
• And maybe, but only maybe, provide support for other led strips (like WS2812, WS2813, WS2815, ... which are all working the same way)

And now I wish you a nice summer and a lot of fun!

Easter Release

CAUTION: THIS RELEASE BREAKS BACKWARDS COMPATIBILITY

Intro

It has been almost 1 year since the last Fledex version was released, so it's high time to release a new version. This version BREAKS compatibility with the previous version, but it should be rather easy to adjust.

If you look through the changes, it should be rather obvious which one breaks compatibility, but for those it might not be, I have tried to give the necessary hints.

Please note that I expect some behavioral changes of the Fledex.Effects in the next version. to better support the newly introduced Coordinator.

New Features:

• Create support for a coordinator (that can control individual animations and effects).
  • This work is not yet complete and therefore you won't find too much documentation about it yet.
  • This also required some updates of the Fledex.Effects to make use of the coordinator functionality by reporting back their state through PubSub.
  • This made the Sequencer effect unnecessary and therefore got removed (it never worked that well anyway).
  • So far the effect state was an Atom, but with the new boardcasting it can be anything. The effect_status type was retained, but is not used and might disappear in the future, even though it would be good to have a basic set of effect states. We'll see!
  • Effects should use Fledex.Effects.Interface (the @behaviour) instead of just implementing it, because it allows to provide default implementations.
  • Effects now also get a context that will be important for the coordinator
  • The Effect configuration now NEEDS to be a keyword list. This made it easy to add the ability to enable/disable animations and effects.
  • Also the Animator became easier/more flexible, because enable/disable is like any other config update.
• Added more color names. It now includes color names from css, svg, ral standards. The latter can not be accessed through the Fledex.Color.Names but only through its own module (since it's not so common)
• Added a Fledex.Color protocol to convert to_colorint() and to_rgb()
  • This also helps in removing cyclic dependencies with the Fledex.Color.Names module
  • Note: the protocol causes the ElixirLS server to give some unknown functions warnings. I was unable to disable them (neither with a @dialyzer tag nor with a dialyzer file). Only thing that helped is to disable dialyzer in ElixirLS (or live with the warnings in your editor).
  • Note: Fledex.Color.Utils was first split. The protocol functions are in Fledex.Color the rest is in Fledex.Color.Conversion.CalcUtils
• Versioning. You can query Fledex about the installed version. This even allows to have DSL scripts that can adapt depending on the version by calling Fledex.version/0
• (Not quite working!): starting Fledex.Animation.Manager as child process of Kino if we opperate in a Kino env (which we currently always do due to the Kino driver dependency :-()

Improvements:

• Big refactoring of the Fledex.Color.Names module.
  • The actual Fledex.Color.Names module delegates most functions to the corresponding color modules (Fledex.Color.Names.{CSS, SVG, Wiki}). I did not delegate to Fledex.Color.Names.RAL because it would be too massive. You will have to alias (or import) that module if you want to use those functions.
  • Split out the guard into a separate file, so it's not necessary to load all functions.
  • Moved the code generating function into a DSL module. This approach also allows to quite easily load from other color modules.
  • The goal was the improve the compilation time, but unfortunately I didn't achieve this.
• Refactored the Fledex.Animation.Manager
  • Better segregation of the animator, job, and coordinator. The manager now knows less about them
  • It doesn't depend on Fledex.LedStrip directly anymore. That helps also during testing.
  • Changing the way how animation names are created
• Refactoring the Fledex.Utils.PubSub module, like renaming the simple_broadcast to broadcast_trigger, since we have now more broadcast types.
• Major refactor of the Fledex.LedStrip and Fledex.Driver.* modules
  • Instead of an atom a module is now used as driver (except for special drivers!). This allows the drivers to provide their default configuration that can easily be overwritten with a keyword list.
  • The LedsDriver.reinit now allows to reconfigure drivers. So for new configs weren't passed in Currently the new config is not passed in
  • Improve the LedsDriver config (Note: that the change_config() function was removed, which was already deprecated in the last version).
    There is now a clear separationg between the LedStrip and Driver configurations.
  • Fix the Fledex.Driver.Impl.SPI driver so that it compares the settings and reopens the channel if necessary
  • Added the possibility to clear the LEDs when initializing the SPI Driver.
  • Removed the default name of the LedStrip. Thus, you have to provide a name explicitly
• Improved the Fledex.Leds module
  • Changed the set_driver_info to set_led_strip_info (NOTE: The above is a breaking change, but a simple search&replace can fix this. If you use the DSL you wouldn't even use it)
  • Code contained a lot of checks that are not necessary when working with the DSL. Therefore they got removed (process running, namespace is defined, ...).
  • Changing in all functions that options are passed as keyword list (rainbow, light, send)
• Cleaning up the function guards in the Dot component
• We parse the configuration for missing functions, so that errors can be detected early on instead of during painting.

Testing

• Reduced the number of tests, that require the Fledex.Animation.Manager to be started. This makes the tests more clear and less flaky.
• 100% test coverage (Exclusions: mox removed since it doesn't make sense to test it and clock & thermometer components since they are still in a testing state)

Cleanup & Build

• refactoring CI pipline.
  • Adding formatting checks
  • Adding graph checks
  • Created dependabot.yml
• Fixing a compile warnings (like the one regarding ranges)
• Remove the "it's taking more than 10sec" warning during compilation. We know the generation of the name files will take more time.
• Fixed most Credo warnings (except the TODOs in code)
• Updating all libraries to their latest version
• Fixing Dialyzer issues
• Refactoring to reduce compile dependencies
• Removing unused code
• Improving type specs (more tight better names, better order, ...)

Bugs:

• Fixed a nasty bug that caused the LedStrip to crash. By mistake I returned the wrong parameter in a function corrupting the state. It only happened during reinit.
• Fixing a bug in the LedStrip. We shouldn't raise an exception, but only return an error if the arguments are wrong

Documentation

• Updated the README.md (that probably was visible much earlier)
• Overhaul of the Livebook documentation (of course with all the necessary changes but also with a lot of more content). Added for example also debugging tricks to the livebook (for components), because it can sometimes be hard to figure out what is happening when the LEDS don't do what you want.
• Overhaul of the livebook READMEE.md file giving an overview of the different livebooks
  • All livebooks are mentioned
  • Added in the Livebook README.md information on what kind (intro, background, usage, details) the livebooks are. This way the reader can check whether it's worthwhile for him/her to read it
• Updated the Architectural Overview to adjust to the new driver approach
• Updated the Cheatsheet.md with new driver approach
• Improved the API documentation (corrected also small mistakes)
• Updated the CREDITS.md
• Updated the TODOs
• Also updated the license files (corrected the license for the external color files)
• Ensured reuse compliance
• Adding documentation for guards

External Feedback

I started to make the library more public. It was presented:

• in a school project and
• talked on an Erlang/Elixir meetup about it.

This provided some good feedback resulting in some of the above mentioned changes

Final words

With this I wish you Happy Easter and I hope you have some fun. The next release shouldn't take quite as much time. Take a look at the latest TODO.md file to see what is planned for v0.6. I always try to keep that file up-to-date.

Spring release

A lot of improvements have gone into this release.

• All macros (animation, static, effect, component, job) seem to be working as expected
• Major code cleanup (still some to go, but good enough for now)
• Major documentation improvements
• some minor breaking changes to make thing smoother, but some radical changes in how to provide functionality.

some more testing will have to go in, but this version should be good enough to try it at a local school to see how creative kids can be.

v0.3.0

Xmas cleanup (!?)

A lot of improvements in all aspects:

• refactored code (CAUTION: a lot of names changed)
• improved API documentation
• improved livebook documentation
• improved typespecs
• improved usability
• new functionality (like introduction of effects

This version has also prepared for components, but the effect work has raised some interesting questions. This probably will mean another refactoring within the Fledex.Animation modules.

I'm quite happy with the dsl even though the the config aspect is still unsatisfactory. something left for v0.4 to be fixed ;-)

v0.2.0

Welcome to animations

This version is a first version that feels more stable. For the functionality provided, no major changes are expected. It introduces the following features:

• LedAnimator a server that manages animations and that can be updated to run a new animation
• LedAnimationManager a server that manages a set of led strips and animations. It manages the lifecycle of them and through a single interface they can be managed
• Full test coverage (note: some test are still flaky, some are not the best)
• Decently good livebook coverage of the current functionality
• Architecture diagram

This is still not production ready, but we surely are getting closer :-)

v0.1.0

First roughly working version

This is the first version that is kind of working. What it provides:

LedsDriver to address a sequence and led strip
Leds to describe a sequence of leds (including some functions to create a rainbow)
some very early documentation with some livebooks

Note: everything is very rough a lot of changes are expected