|
1 | 1 | .. _scripting: |
2 | 2 |
|
3 | 3 | Embedding into Custom Scripts |
4 | | ------------------------------ |
| 4 | +============================= |
5 | 5 |
|
6 | 6 | ``esptool.py``, ``espefuse.py``, and ``espsecure.py`` can easily be integrated into Python applications or called from other Python scripts. |
7 | 7 |
|
8 | 8 | While it currently does have a poor Python API, something which `#208 <https://github.com/espressif/esptool/issues/208>`_ will address, it allows for passing CLI arguments to ``esptool.main()``. This workaround makes integration very straightforward as you can pass exactly the same arguments as you would on the CLI: |
9 | 9 |
|
10 | 10 | .. code-block:: python |
11 | 11 |
|
| 12 | + import esptool |
| 13 | +
|
12 | 14 | command = ['--baud', '460800', 'read_flash', '0', '0x200000', 'flash_contents.bin'] |
13 | | - print('Using command %s' % ' '.join(command)) |
| 15 | + print("Using command ", " ".join(command)) |
14 | 16 | esptool.main(command) |
15 | 17 |
|
16 | 18 |
|
@@ -63,3 +65,63 @@ The following is an example on how to use esptool as a Python module and leverag |
63 | 65 |
|
64 | 66 | # Reset the chip out of bootloader mode |
65 | 67 | esp.hard_reset() |
| 68 | +
|
| 69 | +
|
| 70 | +.. _logging: |
| 71 | + |
| 72 | +Redirecting Output with a Custom Logger |
| 73 | +--------------------------------------- |
| 74 | + |
| 75 | +Esptool allows redirecting output by implementing a custom logger class. This can be useful when integrating esptool with graphical user interfaces or other systems where the default console output is not appropriate. Below is an example demonstrating how to create and use a custom logger: |
| 76 | + |
| 77 | +.. code-block:: python |
| 78 | +
|
| 79 | + from esptool.logger import log, TemplateLogger |
| 80 | +
|
| 81 | + class CustomLogger(TemplateLogger): |
| 82 | + log_to_file = True |
| 83 | + log_file = "esptool.log" |
| 84 | +
|
| 85 | + def print(self, message, *args, **kwargs): |
| 86 | + # Print to console |
| 87 | + print(f"[CustomLogger]: {message}", *args, **kwargs) |
| 88 | + # Optionally log to a file |
| 89 | + if self.log_to_file: |
| 90 | + with open(self.log_file, "a") as log: |
| 91 | + log.write(f"{message}\n") |
| 92 | +
|
| 93 | + def note(self, message): |
| 94 | + self.print(f"NOTE: {message}") |
| 95 | +
|
| 96 | + def warning(self, message): |
| 97 | + self.print(f"WARNING: {message}") |
| 98 | +
|
| 99 | + def error(self, message): |
| 100 | + self.print(message, file=sys.stderr) |
| 101 | +
|
| 102 | + def print_overwrite(self, message): |
| 103 | + # Overwriting not needed, print normally |
| 104 | + self.print(message) |
| 105 | +
|
| 106 | + def set_progress(self, percentage): |
| 107 | + # Progress updates not needed, pass |
| 108 | + pass |
| 109 | +
|
| 110 | + # Replace the default logger with the custom logger |
| 111 | + log.set_logger(CustomLogger()) |
| 112 | +
|
| 113 | + # From now on, all esptool output will be redirected through the custom logger |
| 114 | + # Your code here ... |
| 115 | +
|
| 116 | +In this example, the ``CustomLogger`` class provides additional functionality such as logging messages to a file, which the original ``EsptoolLogger`` (imported from ``esptool.logger`` as an initiated object ``log``) doesn't. The ``EsptoolLogger.set_logger()`` method is used to replace the default logger with the custom logger. |
| 117 | + |
| 118 | +To ensure compatibility with esptool, the custom logger should re-implement (or inherit) the following methods from the original ``EsptoolLogger`` class (see the reference implementation `here <https://github.com/espressif/esptool/blob/master/esptool/logger.py>`__), this is enforced by the ``TemplateLogger`` abstract class: |
| 119 | + |
| 120 | +- ``print``: Handles plain message logging. |
| 121 | +- ``note``: Logs informational messages. |
| 122 | +- ``warning``: Logs warning messages. |
| 123 | +- ``error``: Logs error messages. |
| 124 | +- ``print_overwrite``: Handles message overwriting (can be a simple ``print()`` if overwriting is not needed). |
| 125 | +- ``set_progress``: Handles percentage updates of long-running operations - ``write_flash``, ``read_flash``, and ``dump_mem`` (useful for GUI visualisation, e.g. as a progress bar). |
| 126 | + |
| 127 | +These methods are essential for maintaining proper integration and behavior with esptool. Additionally, all calls to the logger should be made using ``log.print()`` (or the respective method, such as ``log.info()`` or ``log.warning()``) instead of the standard ``print()`` function to ensure the output is routed through the custom logger. This ensures consistency and allows the custom logger to handle all output appropriately. You can further customize this logger to fit your application's needs, such as integrating with GUI components or advanced logging frameworks. |
0 commit comments