.. _flashing:

Flashing
========

The teensy microcontroller is primarily supposed to be connected to and
flashed via USB. Despite we support flashing the firmware via network
(OTP), this mechanism for autonomous self-updates over ethernet are
currently not yet well supported/documented.

How to flash a new (prebuilt) version of the firmware
-----------------------------------------------------

This section is relevant for users who want to flash a given
firmware image onto their Teensy.
If you want to develop on the firmware code or build the firmware image
from code, please read :ref:`build` instead of this section.

You can download the latest stable firmware from the releases page
at Github: https://github.com/anabrid/lucidac-firmware/releases . In this guide, 
you need the ``firmware.hex`` file from the most recent release.

Install the teensy flashing utility from https://www.pjrc.com/teensy/loader_cli.html
to allow flashing the firmware image without prior building at your computer.
If you are working on a Linux computer which was not connected to a
Teensy before, please consider the section :ref:`udev`.

Connect your LUCIDAC via the USB port to your computer.
In order to flash your microcontroller, execute

::

   teensy_loader_cli --mcu=TEENSY41 firmware.hex``

   
.. note::
   
   You might have to run the ``teensy_loader_cli`` multiple times
   (up to two or three times in a row) in order to work. Despite it
   says differently, you do *not* have to press the button on Teensy,
   which comes handy if you don't have it at hand (because it is built
   in some enclosure).
   
Alternatives
------------

You can use the graphical Teensy Loader Application at https://www.pjrc.com/teensy/loader.html, which is suitable when doing a manual update with
a given flash file but not very practical within a command line workflow.

Instead, we have good experiences with alternative tools such
as https://koromix.dev/tytools which is also part of the ``platformio.ini``
in the firmware repository.

Building a newer version of ``teensy_loarder_cli`` then included in PlatformIO
------------------------------------------------------------------------------

If you have the platformio teensy package installed (see :ref:`platformio`),
you find the
flashing utility in ``$HOME/.platformio/packages/tool-teensy/teensy_loader_cli``.
This executable is invoked when calling ``pio run -t upload``.

However, the ``teensy_loader_cli`` bundled with the platformio teensy package is
known to be broken, cf. https://lab.analogparadigm.com/lucidac/firmware/hybrid-controller/-/issues/76.
The workaround is to build a more recent version of the code:

::

    % wget https://github.com/PaulStoffregen/teensy_loader_cli/raw/master/teensy_loader_cli.c
    % apt install gcc libusb-dev  # probably have to install some dependencies
    % gcc -DUSE_LIBUSB teensy_loader_cli.c -oteensy_loader_cli-v2.3 -lusb
    % grep upload platformio.ini  # change accordingly or add lines:
    upload_protocol = custom
    upload_command = ./teensy_loader_cli-v2.3 -mmcu=teensy41 -w -s -v .pio/build/teensy41/firmware.hex
    % pio run -t upload # then this works again