.. index:: color, colourized error messages

.. _errors.colourized:

Colourized Error Messages
=========================
One of the really fantastic things about Mecrisp-Stellaris is that one can easily hack it to suit ones requirements because the source code is GPL'd and Open, and the Author Matthias Koch is friendly and helpful.

Mecrisp-Stellaris has a on-chip compiler, which also emits :ref:`ERROR MESSAGES<cmessages>` as it finds them in Source Code that is being uploaded. 

The errors are displayed in the Terminal screen as they occur, mixed in with the source code, and all displayed in the same default Terminal text colour.

.. image:: projects/colourize-errors/pics/mecrisp-stellaris-default-error-reporting.jpg

Some clever Serial Terminals such as :ref:`E4THCOM<e4thcom>` parse for the known error messages recolouring them and stopping the upload. E4thcom is distributed as a binary and only runs on Linux.

In other :ref:`ARTICLES<code-errors>` I describe the error response system I deploy, namely :

1) Lighting a bright BLUE led on the Target when a ERROR is detected
2) Stop the upload at the actual error via Hardware Handshaking

.. note:: Both these methods tap into the On Chip Compiler Error Message system. It knows all about errors, why not use it ?

Benefit to New Forth Users
--------------------------
When I started learning Forth, I'd often miss a small error message as the upload streamed by in the Terminal. The small error would often lead to subsquent errors that I'd chase not knowing the true cause. It's my hope that new Forthers may also find this method a time saver once implemented.

YouTube Video
-------------
https://youtu.be/vAGTKLZq0PM

Adding Colourized Error Messages to Mecrisp=Stellaris
-----------------------------------------------------
In this article I describe a somewhat easier to deploy method of error message colouring which should work across the entire Mecrisp-Stellaris MCU range with only a couple of Kernel Source code mods, and a Kernel :ref:`REBUILD<rebuild.kernel>`.

Colorized Error Reporting
^^^^^^^^^^^^^^^^^^^^^^^^^
This errors in this picture were contrived by compiling the source to Flash repeatedly until the Flash was full.

.. image:: projects/colourize-errors/pics/mecrisp-stellaris-coloured-errors.jpg


CRITICAL: RED Colouring
~~~~~~~~~~~~~~~~~~~~~~~
Sourcefile: mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/common/datastackandmacros.s

.. note:: This adds the ANSI escape sequence for the color RED indicating CRITICAL errors.  Lines which start with "-" need to be replaced with lines starting with "+"
     
::

   .macro Fehler_Quit_n Meldung
   bl dotgaensefuesschen
   .byte 8f - 7f         @ Compute length of name field.
   
   
   -  7:      .ascii "\Meldung\r\n"
   +  7:      .ascii "\x1B[31;1m\Meldung\x1B[31;0m\r\n"

   8:      .p2align 1
   .endm

WARNING: BLUE Colouring
~~~~~~~~~~~~~~~~~~~~~~~
Sourcefile: mecrisp-stellaris-X.X.X/mecrisp-stellaris-source/common/compiler-flash.s

.. note:: This adds the ANSI escape sequence for the color BLUE indicating a WARNING

::

 -    write "Redefine "
 +    write "\x1B[34;1m Redefine\x1B[34;0m "

Now Rebuild the Kernel
^^^^^^^^^^^^^^^^^^^^^^

:ref:`REBUILD The Kernel<rebuild.kernel>`