mcu_stubber
===========

.. py:module:: mcu_stubber

.. autoapi-nested-parse::

   This script creates stubs on and for a connected micropython MCU board.



Attributes
----------

.. autoapisummary::

   mcu_stubber.HERE
   mcu_stubber.reset_before
   mcu_stubber.TESTING


Classes
-------

.. autoapisummary::

   mcu_stubber.Variant
   mcu_stubber.Form


Functions
---------

.. autoapisummary::

   mcu_stubber.hard_reset
   mcu_stubber.run_createstubs
   mcu_stubber.build_cmd
   mcu_stubber.ensure_lib_directory
   mcu_stubber.generate_board_stubs
   mcu_stubber.copy_boardname_to_board
   mcu_stubber.install_scripts_to_board
   mcu_stubber.get_stubfolder
   mcu_stubber.set_loglevel
   mcu_stubber.copy_to_repo
   mcu_stubber.stub_connected_mcus
   mcu_stubber.print_publish_table
   mcu_stubber.print_stub_locations_table


Module Contents
---------------

.. py:data:: HERE

.. py:data:: reset_before
   :value: True


.. py:data:: TESTING
   :value: False


.. py:class:: Variant

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Variants to generate stubs on a MCU


   .. py:attribute:: full
      :value: 'full'



   .. py:attribute:: mem
      :value: 'mem'



   .. py:attribute:: db
      :value: 'db'



.. py:class:: Form

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Optimization forms of scripts


   .. py:attribute:: py
      :value: 'py'



   .. py:attribute:: min
      :value: 'min'



   .. py:attribute:: mpy
      :value: 'mpy'



.. py:function:: hard_reset(board: mpflash.mpremoteboard.MPRemoteBoard) -> bool

   Reset the board


.. py:function:: run_createstubs(dest: pathlib.Path, mcu: mpflash.mpremoteboard.MPRemoteBoard, variant: Variant = Variant.db, mount_vfs: bool = True)

   Run a createstubs[variant]  on the provided board.
   Retry running the command up to 10 times, with a 15 second timeout between retries.
   this should allow for the boards with little memory to complete even if they run out of memory.


.. py:function:: build_cmd(dest: Union[pathlib.Path, None], variant: Variant = Variant.db) -> List[str]

   Build the import createstubs[_??] command to run on the board


.. py:function:: ensure_lib_directory(mcu: mpflash.mpremoteboard.MPRemoteBoard)

   Create lib directory and add to sys.path for mip_install.

   mpremote mip requires a lib path in sys.path but does not create the
   directory itself. This must be called before mip_install.


.. py:function:: generate_board_stubs(dest: pathlib.Path, mcu: mpflash.mpremoteboard.MPRemoteBoard, variant: Variant = Variant.db, form: Form = Form.mpy, mount_vfs: bool = True, exclude: Union[List[str], None] = None) -> Tuple[int, Optional[pathlib.Path]]

   Generate the firmware stubs (formerly MCU stubs) for this MCU board.
   :param dest: The destination folder for the stubs
   :type dest: Path
   :param port: The port the board is connected to
   :type port: str


.. py:function:: copy_boardname_to_board(mcu: mpflash.mpremoteboard.MPRemoteBoard)

   Copies the board name to the board by writing it to the 'boardname.py' file.

   :param mcu: The MCU object representing the microcontroller.

   :returns: None


.. py:function:: install_scripts_to_board(mcu: mpflash.mpremoteboard.MPRemoteBoard, form: Form)

   Copy the createstubs script(s) to the board.
   The scripts are sourced from the 'board' folder that is included
    - in the micropython-stubber package.
    - or in de repo during development

   :param mcu: The microcontroller unit.
   :type mcu: str
   :param variant: The variant of the board.
   :type variant: str
   :param form: The form of the scripts to be copied.
   :type form: Form

   :returns: True if the scripts are successfully copied, False otherwise.
   :rtype: bool


.. py:function:: get_stubfolder(out: List[str])

.. py:function:: set_loglevel(verbose: int) -> str

   Set log level based on verbose level
   Get the level from the verbose setting (0=INFO, 1=DEBUG, 2=TRACE)
   Set the format string, based on the level.
   Add the handler to the logger, with the level and format string.
   Return the level


.. py:function:: copy_to_repo(source: pathlib.Path, fw: dict) -> Optional[pathlib.Path]

   Copy the generated stubs to the stubs repo.
   If the destination folder exists, it is first emptied
   when successful: returns the destination path - None otherwise


.. py:function:: stub_connected_mcus(variant: str, format: str, debug: bool, serial: List[str], ignore: List[str], bluetooth: bool, exclude: Union[List[str], None] = None, mount_vfs: bool = True) -> int

   Runs the stubber to generate stubs for connected MicroPython boards.

   :param variant: The variant of the createstubs script.
   :type variant: str
   :param format: The format of the createstubs script.
   :type format: str
   :param debug: Flag indicating whether to enable debug mode.
   :type debug: bool

   :returns: None


.. py:function:: print_publish_table(all_built: List, console: Optional[rich.console.Console] = None)

.. py:function:: print_stub_locations_table(stub_locations: List, console: Optional[rich.console.Console] = None)

   Print a table of stub locations for generated stubs.